| 1 | # Contributing Skills to Agent Zero |
| 2 | |
| 3 | Welcome to the Agent Zero Skills ecosystem! This guide will help you create, test, and share skills with the community. |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## What is a Skill? |
| 8 | |
| 9 | A **Skill** is a contextual expertise module that provides the AI agent with specialized knowledge and procedures for specific tasks. Unlike tools (which are always loaded), skills are **surfaced via description/tag matching** when relevant, making them token-efficient and context-aware. |
| 10 | |
| 11 | ### Skills vs Tools vs Knowledge |
| 12 | |
| 13 | | Aspect | Skills | Tools | Knowledge | |
| 14 | |--------|--------|-------|-----------| |
| 15 | | **Loading** | Description/tag matching | Always in prompt | Semantic recall | |
| 16 | | **Purpose** | Procedures & expertise | Actions & functions | Facts & data | |
| 17 | | **Format** | SKILL.md (YAML + Markdown) | Python/code | Text/documents | |
| 18 | | **When to use** | "How to do X" | "Do X now" | "What is X" | |
| 19 | |
| 20 | ### Cross-Platform Compatibility |
| 21 | |
| 22 | The SKILL.md standard is compatible with: |
| 23 | - **Agent Zero** (this project) |
| 24 | - **Claude Code** (Anthropic) |
| 25 | - **Cursor** (AI IDE) |
| 26 | - **OpenAI Codex CLI** |
| 27 | - **GitHub Copilot** |
| 28 | - **Goose** (Block) |
| 29 | |
| 30 | Skills you create here can be used in any of these platforms! |
| 31 | |
| 32 | --- |
| 33 | |
| 34 | ## Quick Start |
| 35 | |
| 36 | ### Using the CLI (Recommended) |
| 37 | |
| 38 | ```bash |
| 39 | # Create a new skill interactively |
| 40 | python -m helpers.skills_cli create my-skill-name |
| 41 | |
| 42 | # List all available skills |
| 43 | python -m helpers.skills_cli list |
| 44 | |
| 45 | # Validate a skill |
| 46 | python -m helpers.skills_cli validate my-skill-name |
| 47 | |
| 48 | # Search skills |
| 49 | python -m helpers.skills_cli search "keyword" |
| 50 | ``` |
| 51 | |
| 52 | ### Manual Creation |
| 53 | |
| 54 | 1. Create a folder in `usr/skills/` with your skill name |
| 55 | 2. Add a `SKILL.md` file with YAML frontmatter |
| 56 | 3. Optionally add supporting scripts (`.py`, `.sh`, `.js`) |
| 57 | |
| 58 | --- |
| 59 | |
| 60 | ## SKILL.md Standard |
| 61 | |
| 62 | Every skill must have a `SKILL.md` file with this structure: |
| 63 | |
| 64 | ```markdown |
| 65 | --- |
| 66 | name: "skill-name" |
| 67 | description: "A clear, concise description of what this skill does and when to use it" |
| 68 | version: "1.0.0" |
| 69 | author: "Your Name <email@example.com>" |
| 70 | license: "MIT" |
| 71 | tags: ["category", "purpose", "technology"] |
| 72 | triggers: |
| 73 | - "keyword that activates this skill" |
| 74 | - "another trigger phrase" |
| 75 | allowed_tools: |
| 76 | - tool_name |
| 77 | - another_tool |
| 78 | metadata: |
| 79 | complexity: "beginner|intermediate|advanced" |
| 80 | category: "development|devops|data|productivity|creative" |
| 81 | estimated_time: "5 minutes" |
| 82 | --- |
| 83 | |
| 84 | # Skill Name |
| 85 | |
| 86 | ## Overview |
| 87 | |
| 88 | Brief description of what this skill accomplishes. |
| 89 | |
| 90 | ## When to Use |
| 91 | |
| 92 | - Situation 1 where this skill applies |
| 93 | - Situation 2 where this skill applies |
| 94 | |
| 95 | ## Instructions |
| 96 | |
| 97 | ### Step 1: First Step |
| 98 | |
| 99 | Detailed instructions... |
| 100 | |
| 101 | ### Step 2: Second Step |
| 102 | |
| 103 | More instructions... |
| 104 | |
| 105 | ## Examples |
| 106 | |
| 107 | ### Example 1: Basic Usage |
| 108 | |
| 109 | \`\`\`python |
| 110 | # Code example |
| 111 | \`\`\` |
| 112 | |
| 113 | ### Example 2: Advanced Usage |
| 114 | |
| 115 | \`\`\`python |
| 116 | # Advanced code example |
| 117 | \`\`\` |
| 118 | |
| 119 | ## Common Pitfalls |
| 120 | |
| 121 | - Pitfall 1 and how to avoid it |
| 122 | - Pitfall 2 and how to avoid it |
| 123 | |
| 124 | ## Related Skills |
| 125 | |
| 126 | - `related-skill-1` |
| 127 | - `related-skill-2` |
| 128 | ``` |
| 129 | |
| 130 | ### Required Fields |
| 131 | |
| 132 | | Field | Description | |
| 133 | |-------|-------------| |
| 134 | | `name` | Unique identifier (lowercase, hyphens allowed) | |
| 135 | | `description` | What the skill does (used for semantic matching) | |
| 136 | |
| 137 | ### Optional Fields |
| 138 | |
| 139 | | Field | Description | |
| 140 | |-------|-------------| |
| 141 | | `version` | Semantic version (e.g., "1.0.0") | |
| 142 | | `author` | Your name and email | |
| 143 | | `license` | License (MIT, Apache-2.0, etc.) | |
| 144 | | `tags` | Categories for discovery | |
| 145 | | `triggers` | Phrases that activate this skill | |
| 146 | | `allowed_tools` | Tools this skill can use | |
| 147 | | `metadata` | Additional structured data | |
| 148 | |
| 149 | --- |
| 150 | |
| 151 | ## Creating Your First Skill |
| 152 | |
| 153 | ### Step 1: Identify the Need |
| 154 | |
| 155 | Ask yourself: |
| 156 | - What expertise would help the agent? |
| 157 | - When should this skill be activated? |
| 158 | - What steps should the agent follow? |
| 159 | |
| 160 | ### Step 2: Create the Structure |
| 161 | |
| 162 | ```bash |
| 163 | # Using CLI |
| 164 | python -m helpers.skills_cli create my-awesome-skill |
| 165 | |
| 166 | # Or manually |
| 167 | mkdir -p usr/skills/my-awesome-skill |
| 168 | touch usr/skills/my-awesome-skill/SKILL.md |
| 169 | ``` |
| 170 | |
| 171 | ### Step 3: Write the SKILL.md |
| 172 | |
| 173 | ```markdown |
| 174 | --- |
| 175 | name: "my-awesome-skill" |
| 176 | description: "Helps with [specific task] when [specific situation]" |
| 177 | version: "1.0.0" |
| 178 | author: "Your Name" |
| 179 | tags: ["category"] |
| 180 | --- |
| 181 | |
| 182 | # My Awesome Skill |
| 183 | |
| 184 | ## When to Use |
| 185 | |
| 186 | Use this skill when you need to [specific task]. |
| 187 | |
| 188 | ## Instructions |
| 189 | |
| 190 | 1. First, do this... |
| 191 | 2. Then, do that... |
| 192 | 3. Finally, verify by... |
| 193 | |
| 194 | ## Examples |
| 195 | |
| 196 | ### Example: Basic Case |
| 197 | |
| 198 | [Show a complete example] |
| 199 | ``` |
| 200 | |
| 201 | ### Step 4: Add Supporting Files (Optional) |
| 202 | |
| 203 | If your skill needs scripts: |
| 204 | |
| 205 | ``` |
| 206 | my-awesome-skill/ |
| 207 | ├── SKILL.md # Required |
| 208 | ├── helper.py # Optional Python script |
| 209 | ├── setup.sh # Optional shell script |
| 210 | └── templates/ # Optional templates folder |
| 211 | └── config.json |
| 212 | ``` |
| 213 | |
| 214 | Reference them in your SKILL.md: |
| 215 | |
| 216 | ```markdown |
| 217 | ## Scripts |
| 218 | |
| 219 | This skill includes helper scripts: |
| 220 | - `helper.py` - Does X |
| 221 | - `setup.sh` - Sets up Y |
| 222 | ``` |
| 223 | |
| 224 | ### Step 5: Test Your Skill |
| 225 | |
| 226 | ```bash |
| 227 | # Validate the skill |
| 228 | python -m helpers.skills_cli validate my-awesome-skill |
| 229 | |
| 230 | # Test in Agent Zero |
| 231 | # Start the agent and ask it to perform the task your skill handles |
| 232 | ``` |
| 233 | |
| 234 | --- |
| 235 | |
| 236 | ## Best Practices |
| 237 | |
| 238 | ### Writing Effective Descriptions |
| 239 | |
| 240 | The `description` field is crucial for semantic matching. Make it: |
| 241 | |
| 242 | **Good:** |
| 243 | ```yaml |
| 244 | description: "Guides systematic debugging of Python applications using print statements, debugger, and logging to identify root causes" |
| 245 | ``` |
| 246 | |
| 247 | **Bad:** |
| 248 | ```yaml |
| 249 | description: "Helps with debugging" |
| 250 | ``` |
| 251 | |
| 252 | ### Structuring Instructions |
| 253 | |
| 254 | 1. **Be Specific** - Avoid vague instructions |
| 255 | 2. **Use Steps** - Number your steps clearly |
| 256 | 3. **Include Examples** - Show, don't just tell |
| 257 | 4. **Anticipate Errors** - Include troubleshooting |
| 258 | |
| 259 | ### Semantic Triggers |
| 260 | |
| 261 | Design your description and content so the skill is recalled when relevant: |
| 262 | |
| 263 | ```yaml |
| 264 | # Include synonyms and related terms |
| 265 | description: "Helps create REST APIs, web services, HTTP endpoints, and backend routes using FastAPI, Flask, or Express" |
| 266 | ``` |
| 267 | |
| 268 | ### Keep Skills Focused |
| 269 | |
| 270 | One skill = one expertise area. If your skill is getting too long, split it: |
| 271 | |
| 272 | - `api-design` - API structure and patterns |
| 273 | - `api-security` - API authentication and authorization |
| 274 | - `api-testing` - API testing strategies |
| 275 | |
| 276 | --- |
| 277 | |
| 278 | ## Testing Skills |
| 279 | |
| 280 | ### Local Testing |
| 281 | |
| 282 | 1. **Validate Structure:** |
| 283 | ```bash |
| 284 | python -m helpers.skills_cli validate my-skill |
| 285 | ``` |
| 286 | |
| 287 | 2. **Test Semantic Recall:** |
| 288 | Start Agent Zero and ask questions that should trigger your skill. |
| 289 | |
| 290 | 3. **Verify Instructions:** |
| 291 | Follow your own instructions manually to ensure they work. |
| 292 | |
| 293 | --- |
| 294 | |
| 295 | ## Sharing Skills |
| 296 | |
| 297 | ### Contributing to Agent Zero |
| 298 | |
| 299 | 1. **Fork the Repository:** |
| 300 | ```bash |
| 301 | git clone https://github.com/agent0ai/agent-zero.git |
| 302 | cd agent-zero |
| 303 | ``` |
| 304 | |
| 305 | 2. **Create Your Skill:** |
| 306 | ```bash |
| 307 | python -m helpers.skills_cli create my-skill |
| 308 | # Edit usr/skills/my-skill/SKILL.md |
| 309 | ``` |
| 310 | |
| 311 | 3. **Move to Default (for contribution):** |
| 312 | ```bash |
| 313 | mv usr/skills/my-skill skills/my-skill |
| 314 | ``` |
| 315 | |
| 316 | 4. **Create a Pull Request:** |
| 317 | - Branch: `feat/skill-my-skill-name` |
| 318 | - Title: `feat(skills): add my-skill-name skill` |
| 319 | - Description: Explain what the skill does and why it's useful |
| 320 | |
| 321 | ### Publishing Skills |
| 322 | |
| 323 | Share your skills on [skillsmp.com](https://skillsmp.com) or [skills.sh](https://skills.sh): |
| 324 | |
| 325 | 1. Create a GitHub repository for your skill |
| 326 | 2. Ensure it follows the SKILL.md standard |
| 327 | 3. Submit via their contribution process |
| 328 | |
| 329 | ### Creating a Skills Collection |
| 330 | |
| 331 | For multiple related skills, create a repository: |
| 332 | |
| 333 | ``` |
| 334 | my-skills-collection/ |
| 335 | ├── README.md |
| 336 | ├── skills/ |
| 337 | │ ├── skill-1/ |
| 338 | │ │ └── SKILL.md |
| 339 | │ ├── skill-2/ |
| 340 | │ │ └── SKILL.md |
| 341 | │ └── skill-3/ |
| 342 | │ └── SKILL.md |
| 343 | └── LICENSE |
| 344 | ``` |
| 345 | |
| 346 | --- |
| 347 | |
| 348 | ## Community Guidelines |
| 349 | |
| 350 | ### Quality Standards |
| 351 | |
| 352 | - **Tested** - Skills must be tested before submission |
| 353 | - **Documented** - Clear instructions and examples |
| 354 | - **Focused** - One expertise per skill |
| 355 | - **Original** - Don't duplicate existing skills |
| 356 | |
| 357 | ### Naming Conventions |
| 358 | |
| 359 | - Use lowercase with hyphens: `my-skill-name` |
| 360 | - Be descriptive: `python-debugging` not `debug` |
| 361 | - Avoid generic names: `fastapi-crud` not `api` |
| 362 | |
| 363 | ### License |
| 364 | |
| 365 | - Include a license (MIT recommended for maximum compatibility) |
| 366 | - Respect licenses of any code you include |
| 367 | - Don't include proprietary or copyrighted content |
| 368 | |
| 369 | --- |
| 370 | |
| 371 | ## FAQ |
| 372 | |
| 373 | ### Q: Where should I put my skills? |
| 374 | |
| 375 | **A:** During development, use `usr/skills/`. For contribution, move to `skills/`. |
| 376 | |
| 377 | ### Q: How are skills discovered? |
| 378 | |
| 379 | **A:** Skills are matched against their name, description, and tags for the current query. They are not indexed into vector memory. |
| 380 | |
| 381 | ### Q: Can I use skills from other platforms? |
| 382 | |
| 383 | **A:** Yes! The SKILL.md standard is cross-platform. Skills from Claude Code, Cursor, or other compatible platforms can be copied directly to `usr/skills/`. |
| 384 | |
| 385 | ### Q: How do I update a skill? |
| 386 | |
| 387 | **A:** Edit the SKILL.md file and increment the version number. Changes take effect on agent restart. |
| 388 | |
| 389 | ### Q: Can skills call other skills? |
| 390 | |
| 391 | **A:** Skills don't directly call each other, but the agent may combine multiple skills when appropriate for a task. |
| 392 | |
| 393 | --- |
| 394 | |
| 395 | Happy skill building! 🚀 |