Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
254 lines (174 loc) · 5.86 KB

CONTRIBUTING.md

File metadata and controls

254 lines (174 loc) · 5.86 KB
Raw

Contributing to Awesome OpenClaw Agents

We welcome community agents! Submit yours and get it listed on crewclaw.com/agents.

Agent File System

Each agent is more than a prompt. It's a full operating system.

agents/[category]/[agent-name]/
├── SOUL.md          ← Identity & personality (required)
├── README.md        ← Description & use cases (required)
├── AGENTS.md        ← Operating rules & instructions (optional)
├── HEARTBEAT.md     ← Wake-up checklist (optional)
└── WORKING.md       ← Starting task template (optional)

SOUL.md and README.md are required. The rest are optional but make your agent production-ready.

Submit Your Agent

Option 1: Pull Request (recommended)

Step 1: Fork & clone

git clone https://github.com/YOUR-USERNAME/awesome-openclaw-agents.git
cd awesome-openclaw-agents

Step 2: Create your agent folder

mkdir -p agents/[category]/[agent-name]

Categories: business, creative, data, development, devops, ecommerce, education, finance, freelance, healthcare, hr, legal, marketing, personal, productivity, real-estate, saas, security

Step 3: Write your SOUL.md (required)

Who is this agent? What's their personality?

# Agent Name

Brief description of the agent.

## Core Identity

- **Role:** What the agent does
- **Personality:** How it behaves
- **Communication:** How it talks

## Responsibilities

1. **Primary Task**
   - Detail 1
   - Detail 2

## Behavioral Guidelines

### Do:
- Good behavior 1

### Don't:
- Bad behavior 1

## Example Interactions

**User:** Example prompt
**Agent:** Example response

Step 4: Write your README.md (required)

# Agent Name

> One-line description

## Overview

What this agent does and why it's useful.

## Use Cases

| Request | Output |
|---------|--------|
| Example 1 | Result 1 |

## Files

| File | Purpose |
|------|---------|
| SOUL.md | Agent identity and personality |
| AGENTS.md | Operating rules |
| HEARTBEAT.md | Wake-up checklist |
| WORKING.md | Starting task |

## Author

Created by [@your-username](https://github.com/your-username)

Step 5: Add AGENTS.md (optional)

How should the agent operate? What are the rules?

# AGENTS.md — Operating Rules

## Workspace
- Read/write files in your workspace directory
- Store findings in memory/ folder
- Log daily activity in memory/YYYY-MM-DD.md

## Communication
- Post updates to task threads
- Use @mentions to notify other agents
- Keep messages concise and actionable

## Tools
- File system: read, write, search
- Shell: run scripts, check logs
- Web: browse, research, fetch data

## Rules
- Always check WORKING.md on startup
- Update WORKING.md after completing a task
- Never make decisions outside your domain
- Ask for clarification instead of guessing

Step 6: Add HEARTBEAT.md (optional)

What should the agent check every time it wakes up?

# HEARTBEAT.md — Wake-Up Checklist

## On Wake
- [ ] Read WORKING.md for current task
- [ ] Check for @mentions and notifications
- [ ] Review assigned tasks

## Periodic
- [ ] Scan activity feed for relevant updates
- [ ] Check if blocked tasks can be unblocked
- [ ] Update daily notes in memory/

## Stand Down
- If no tasks and no mentions, reply HEARTBEAT_OK

Step 7: Add WORKING.md (optional)

What's the agent's starting state?

# WORKING.md — Current State

## Current Task
No active task. Waiting for assignment.

## Context
- Agent deployed and ready
- All integrations connected

## Next Steps
1. Check task board for new assignments
2. Review any pending @mentions
3. Begin work on highest priority item

Step 8: Add entry to agents.json

{
  "id": "your-agent-name",
  "category": "category",
  "name": "Your Agent Name",
  "role": "One-line role description",
  "path": "agents/category/your-agent-name/SOUL.md",
  "deploy": "https://crewclaw.com/create-agent"
}

Step 9: Submit PR

git add .
git commit -m "Add [AgentName] agent template"
git push origin main

Option 2: Issue

Don't want to set up a PR? Use the Submit Your Agent issue template. Paste your SOUL.md and we'll add it for you.

What Happens After Merge

  1. Your agent appears in the registry
  2. Listed on crewclaw.com/agents with deploy button
  3. You get credited as the author
  4. Community can deploy your agent with one click

Submission Tiers

Tier Files Badge
Basic SOUL.md + README.md Community Agent
Standard + AGENTS.md Production Agent
Full + HEARTBEAT.md + WORKING.md Full Agent OS

Full submissions get highlighted in the registry.

Style Guidelines

  • Agent names: Descriptive. CodeReviewer not CR
  • SOUL.md: Clear headers, example interactions, specific behavioral guidelines
  • AGENTS.md: Concrete rules, not vague suggestions
  • HEARTBEAT.md: Actionable checklist, not prose
  • README: Start with name + one-liner, include use case table, credit author

PR Checklist

  • SOUL.md follows the template above
  • README.md included
  • Entry added to agents.json
  • Agent tested (works with OpenClaw or similar framework)
  • No broken links
  • (Optional) AGENTS.md, HEARTBEAT.md, WORKING.md included

Review Process

  1. Maintainer reviews within 48 hours
  2. Feedback if changes needed
  3. Merged and deployed to crewclaw.com/agents

Questions? Open a discussion.