docs/developer/contributing-skills.md
Welcome to the Agent Zero Skills ecosystem! This guide will help you create, test, and share skills with the community.
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.
| Aspect | Skills | Tools | Knowledge |
|---|---|---|---|
| Loading | Description/tag matching | Always in prompt | Semantic recall |
| Purpose | Procedures & expertise | Actions & functions | Facts & data |
| Format | SKILL.md (YAML + Markdown) | Python/code | Text/documents |
| When to use | "How to do X" | "Do X now" | "What is X" |
The SKILL.md standard is compatible with:
Skills you create here can be used in any of these platforms!
# Create a new skill interactively
python -m helpers.skills_cli create my-skill-name
# List all available skills
python -m helpers.skills_cli list
# Validate a skill
python -m helpers.skills_cli validate my-skill-name
# Search skills
python -m helpers.skills_cli search "keyword"
usr/skills/ with your skill nameSKILL.md file with YAML frontmatter.py, .sh, .js)Every skill must have a SKILL.md file with this structure:
---
name: "skill-name"
description: "A clear, concise description of what this skill does and when to use it"
version: "1.0.0"
author: "Your Name <[email protected]>"
license: "MIT"
tags: ["category", "purpose", "technology"]
triggers:
- "keyword that activates this skill"
- "another trigger phrase"
allowed_tools:
- tool_name
- another_tool
metadata:
complexity: "beginner|intermediate|advanced"
category: "development|devops|data|productivity|creative"
estimated_time: "5 minutes"
---
# Skill Name
## Overview
Brief description of what this skill accomplishes.
## When to Use
- Situation 1 where this skill applies
- Situation 2 where this skill applies
## Instructions
### Step 1: First Step
Detailed instructions...
### Step 2: Second Step
More instructions...
## Examples
### Example 1: Basic Usage
\`\`\`python
# Code example
\`\`\`
### Example 2: Advanced Usage
\`\`\`python
# Advanced code example
\`\`\`
## Common Pitfalls
- Pitfall 1 and how to avoid it
- Pitfall 2 and how to avoid it
## Related Skills
- [related-skill-1](../related-skill-1/SKILL.md)
- [related-skill-2](../related-skill-2/SKILL.md)
| Field | Description |
|---|---|
name | Unique identifier (lowercase, hyphens allowed) |
description | What the skill does (used for semantic matching) |
| Field | Description |
|---|---|
version | Semantic version (e.g., "1.0.0") |
author | Your name and email |
license | License (MIT, Apache-2.0, etc.) |
tags | Categories for discovery |
triggers | Phrases that activate this skill |
allowed_tools | Tools this skill can use |
metadata | Additional structured data |
Ask yourself:
# Using CLI
python -m helpers.skills_cli create my-awesome-skill
# Or manually
mkdir -p usr/skills/my-awesome-skill
touch usr/skills/my-awesome-skill/SKILL.md
---
name: "my-awesome-skill"
description: "Helps with [specific task] when [specific situation]"
version: "1.0.0"
author: "Your Name"
tags: ["category"]
---
# My Awesome Skill
## When to Use
Use this skill when you need to [specific task].
## Instructions
1. First, do this...
2. Then, do that...
3. Finally, verify by...
## Examples
### Example: Basic Case
[Show a complete example]
If your skill needs scripts:
my-awesome-skill/
├── SKILL.md # Required
├── helper.py # Optional Python script
├── setup.sh # Optional shell script
└── templates/ # Optional templates folder
└── config.json
Reference them in your SKILL.md:
## Scripts
This skill includes helper scripts:
- `helper.py` - Does X
- `setup.sh` - Sets up Y
# Validate the skill
python -m helpers.skills_cli validate my-awesome-skill
# Test in Agent Zero
# Start the agent and ask it to perform the task your skill handles
The description field is crucial for semantic matching. Make it:
Good:
description: "Guides systematic debugging of Python applications using print statements, debugger, and logging to identify root causes"
Bad:
description: "Helps with debugging"
Design your description and content so the skill is recalled when relevant:
# Include synonyms and related terms
description: "Helps create REST APIs, web services, HTTP endpoints, and backend routes using FastAPI, Flask, or Express"
One skill = one expertise area. If your skill is getting too long, split it:
api-design - API structure and patternsapi-security - API authentication and authorizationapi-testing - API testing strategiesValidate Structure:
python -m helpers.skills_cli validate my-skill
Test Semantic Recall: Start Agent Zero and ask questions that should trigger your skill.
Verify Instructions: Follow your own instructions manually to ensure they work.
Fork the Repository:
git clone https://github.com/agent0ai/agent-zero.git
cd agent-zero
Create Your Skill:
python -m helpers.skills_cli create my-skill
# Edit usr/skills/my-skill/SKILL.md
Move to Default (for contribution):
mv usr/skills/my-skill skills/my-skill
Create a Pull Request:
feat/skill-my-skill-namefeat(skills): add my-skill-name skillShare your skills on skillsmp.com or skills.sh:
For multiple related skills, create a repository:
my-skills-collection/
├── README.md
├── skills/
│ ├── skill-1/
│ │ └── SKILL.md
│ ├── skill-2/
│ │ └── SKILL.md
│ └── skill-3/
│ └── SKILL.md
└── LICENSE
my-skill-namepython-debugging not debugfastapi-crud not apiA: During development, use usr/skills/. For contribution, move to skills/.
A: Skills are matched against their name, description, and tags for the current query. They are not indexed into vector memory.
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/.
A: Edit the SKILL.md file and increment the version number. Changes take effect on agent restart.
A: Skills don't directly call each other, but the agent may combine multiple skills when appropriate for a task.
Happy skill building! 🚀