Skip to content

Agent Zero AI framework

docs: add comprehensive SKILL.md contribution guide

TerminallyLazy8693a9e6c6a3
diff --git a/docs/CONTRIBUTING-SKILLS.md b/docs/CONTRIBUTING-SKILLS.md
new file mode 100644
index 000000000..c8c68fcaa
--- /dev/null
+++ b/docs/CONTRIBUTING-SKILLS.md
@@ -0,0 +1,468 @@
+# Contributing Skills to Agent Zero
+
+Welcome to the Agent Zero Skills ecosystem! This guide will help you create, test, and share skills with the community.
+
+## Table of Contents
+
+- [What is a Skill?](#what-is-a-skill)
+- [Quick Start](#quick-start)
+- [SKILL.md Standard](#skillmd-standard)
+- [Creating Your First Skill](#creating-your-first-skill)
+- [Best Practices](#best-practices)
+- [Testing Skills](#testing-skills)
+- [Sharing Skills](#sharing-skills)
+- [Community Guidelines](#community-guidelines)
+
+---
+
+## What is a Skill?
+
+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 **semantically recalled** when relevant, making them token-efficient and context-aware.
+
+### Skills vs Tools vs Knowledge
+
+| Aspect | Skills | Tools | Knowledge |
+|--------|--------|-------|-----------|
+| **Loading** | Semantic recall | 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" |
+
+### Cross-Platform Compatibility
+
+The SKILL.md standard is compatible with:
+- **Agent Zero** (this project)
+- **Claude Code** (Anthropic)
+- **Cursor** (AI IDE)
+- **OpenAI Codex CLI**
+- **GitHub Copilot**
+- **Goose** (Block)
+
+Skills you create here can be used in any of these platforms!
+
+---
+
+## Quick Start
+
+### Using the CLI (Recommended)
+
+```bash
+# Create a new skill interactively
+python -m python.helpers.skills_cli create my-skill-name
+
+# List all available skills
+python -m python.helpers.skills_cli list
+
+# Validate a skill
+python -m python.helpers.skills_cli validate my-skill-name
+
+# Search skills
+python -m python.helpers.skills_cli search "keyword"
+```
+
+### Manual Creation
+
+1. Create a folder in `skills/custom/` with your skill name
+2. Add a `SKILL.md` file with YAML frontmatter
+3. Optionally add supporting scripts (`.py`, `.sh`, `.js`)
+
+---
+
+## SKILL.md Standard
+
+Every skill must have a `SKILL.md` file with this structure:
+
+```markdown
+---
+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)
+```
+
+### Required Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Unique identifier (lowercase, hyphens allowed) |
+| `description` | What the skill does (used for semantic matching) |
+
+### Optional Fields
+
+| 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 |
+
+---
+
+## Creating Your First Skill
+
+### Step 1: Identify the Need
+
+Ask yourself:
+- What expertise would help the agent?
+- When should this skill be activated?
+- What steps should the agent follow?
+
+### Step 2: Create the Structure
+
+```bash
+# Using CLI
+python -m python.helpers.skills_cli create my-awesome-skill
+
+# Or manually
+mkdir -p skills/custom/my-awesome-skill
+touch skills/custom/my-awesome-skill/SKILL.md
+```
+
+### Step 3: Write the SKILL.md
+
+```markdown
+---
+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]
+```
+
+### Step 4: Add Supporting Files (Optional)
+
+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:
+
+```markdown
+## Scripts
+
+This skill includes helper scripts:
+- `helper.py` - Does X
+- `setup.sh` - Sets up Y
+```
+
+### Step 5: Test Your Skill
+
+```bash
+# Validate the skill
+python -m python.helpers.skills_cli validate my-awesome-skill
+
+# Test in Agent Zero
+# Start the agent and ask it to perform the task your skill handles
+```
+
+---
+
+## Best Practices
+
+### Writing Effective Descriptions
+
+The `description` field is crucial for semantic matching. Make it:
+
+**Good:**
+```yaml
+description: "Guides systematic debugging of Python applications using print statements, debugger, and logging to identify root causes"
+```
+
+**Bad:**
+```yaml
+description: "Helps with debugging"
+```
+
+### Structuring Instructions
+
+1. **Be Specific** - Avoid vague instructions
+2. **Use Steps** - Number your steps clearly
+3. **Include Examples** - Show, don't just tell
+4. **Anticipate Errors** - Include troubleshooting
+
+### Semantic Triggers
+
+Design your description and content so the skill is recalled when relevant:
+
+```yaml
+# Include synonyms and related terms
+description: "Helps create REST APIs, web services, HTTP endpoints, and backend routes using FastAPI, Flask, or Express"
+```
+
+### Keep Skills Focused
+
+One skill = one expertise area. If your skill is getting too long, split it:
+
+- `api-design` - API structure and patterns
+- `api-security` - API authentication and authorization
+- `api-testing` - API testing strategies
+
+---
+
+## Testing Skills
+
+### Local Testing
+
+1. **Validate Structure:**
+ ```bash
+ python -m python.helpers.skills_cli validate my-skill
+ ```
+
+2. **Test Semantic Recall:**
+ Start Agent Zero and ask questions that should trigger your skill.
+
+3. **Verify Instructions:**
+ Follow your own instructions manually to ensure they work.
+
+### Automated Testing
+
+Create a test file `test_skill.py` in your skill folder:
+
+```python
+"""Tests for my-awesome-skill"""
+import pytest
+from python.helpers.skills import SkillManager
+
+def test_skill_loads():
+ manager = SkillManager()
+ skill = manager.get_skill("my-awesome-skill")
+ assert skill is not None
+ assert skill.name == "my-awesome-skill"
+
+def test_skill_has_required_fields():
+ manager = SkillManager()
+ skill = manager.get_skill("my-awesome-skill")
+ assert skill.description
+ assert len(skill.description) > 20
+```
+
+---
+
+## Sharing Skills
+
+### Contributing to Agent Zero
+
+1. **Fork the Repository:**
+ ```bash
+ git clone https://github.com/agent0ai/agent-zero.git
+ cd agent-zero
+ ```
+
+2. **Create Your Skill:**
+ ```bash
+ python -m python.helpers.skills_cli create my-skill
+ # Edit skills/custom/my-skill/SKILL.md
+ ```
+
+3. **Move to Builtin (for contribution):**
+ ```bash
+ mv skills/custom/my-skill skills/builtin/my-skill
+ ```
+
+4. **Create a Pull Request:**
+ - Branch: `feat/skill-my-skill-name`
+ - Title: `feat(skills): add my-skill-name skill`
+ - Description: Explain what the skill does and why it's useful
+
+### Publishing to Skills Marketplace
+
+Share your skills on [skillsmp.com](https://skillsmp.com):
+
+1. Create a GitHub repository for your skill
+2. Ensure it follows the SKILL.md standard
+3. Submit to the marketplace via their contribution process
+
+### Creating a Skills Collection
+
+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
+```
+
+---
+
+## Community Guidelines
+
+### Quality Standards
+
+- **Tested** - Skills must be tested before submission
+- **Documented** - Clear instructions and examples
+- **Focused** - One expertise per skill
+- **Original** - Don't duplicate existing skills
+
+### Naming Conventions
+
+- Use lowercase with hyphens: `my-skill-name`
+- Be descriptive: `python-debugging` not `debug`
+- Avoid generic names: `fastapi-crud` not `api`
+
+### License
+
+- Include a license (MIT recommended for maximum compatibility)
+- Respect licenses of any code you include
+- Don't include proprietary or copyrighted content
+
+### Code of Conduct
+
+- Be respectful in all interactions
+- Provide constructive feedback
+- Help newcomers learn
+- Report issues responsibly
+
+---
+
+## Resources
+
+### Official Documentation
+
+- [Agent Zero Documentation](./README.md)
+- [Architecture Guide](./architecture.md)
+- [Skills System](./architecture.md#skills-system)
+
+### Community
+
+- [GitHub Issues](https://github.com/agent0ai/agent-zero/issues)
+- [Discussions](https://github.com/agent0ai/agent-zero/discussions)
+
+### External Resources
+
+- [Skills Marketplace](https://skillsmp.com)
+- [Awesome Agent Skills](https://github.com/skillmatic-ai/awesome-agent-skills)
+- [Anthropic Skills Repository](https://github.com/anthropics/skills)
+
+---
+
+## FAQ
+
+### Q: Where should I put my skills?
+
+**A:** During development, use `skills/custom/`. For contribution, move to `skills/builtin/`.
+
+### Q: How are skills discovered?
+
+**A:** Skills are indexed in a vector database. When you ask the agent something, it searches for relevant skills based on semantic similarity to your query.
+
+### Q: Can I use skills from other platforms?
+
+**A:** Yes! The SKILL.md standard is cross-platform. Skills from Claude Code, Cursor, or other compatible platforms can be copied directly to `skills/shared/`.
+
+### Q: How do I update a skill?
+
+**A:** Edit the SKILL.md file and increment the version number. Changes take effect on agent restart.
+
+### Q: Can skills call other skills?
+
+**A:** Skills don't directly call each other, but the agent may combine multiple skills when appropriate for a task.
+
+---
+
+## Example Skills to Learn From
+
+Check out these well-structured skills in `skills/builtin/`:
+
+- `brainstorming/` - Requirements exploration workflow
+- `debugging/` - Systematic debugging methodology
+- `tdd/` - Test-driven development process
+- `code_review/` - Comprehensive review checklist
+- `create_skill/` - Meta-skill for creating new skills
+
+---
+
+Happy skill building! 🚀