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.

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 surfaced via description/tag matching when relevant, making them token-efficient and context-aware.

Skills vs Tools vs Knowledge

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)

# 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"

Manual Creation

1. Create a folder in usr/skills/ 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:

---
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@example.com>"
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-2`

Required Fields

Optional Fields

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

# 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

Step 3: Write the 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]

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:

## Scripts

This skill includes helper scripts:
- `helper.py` - Does X
- `setup.sh` - Sets up Y

Step 5: Test Your Skill

# 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

Best Practices

Writing Effective Descriptions

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"

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:

# 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:

   python -m 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.

Sharing Skills

Contributing to Agent Zero

1. Fork the Repository:

   git clone https://github.com/agent0ai/agent-zero.git
   cd agent-zero
   

2. Create Your Skill:

   python -m helpers.skills_cli create my-skill
   # Edit usr/skills/my-skill/SKILL.md
   

3. Move to Default (for contribution):

   mv usr/skills/my-skill skills/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 Skills

Share your skills on skillsmp.com or skills.sh:

1. Create a GitHub repository for your skill
2. Ensure it follows the SKILL.md standard
3. Submit 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

FAQ

Q: Where should I put my skills?

A: During development, use usr/skills/. For contribution, move to skills/.

Q: How are skills discovered?

A: Skills are matched against their name, description, and tags for the current query. They are not indexed into vector memory.

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 usr/skills/.

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.

Happy skill building! 🚀

Source: docs/developer/contributing-skills.md