docs: add comprehensive SKILL.md contribution guide
Add CONTRIBUTING-SKILLS.md with complete documentation for: - SKILL.md standard format with YAML frontmatter - Quick start guide using CLI tool - Step-by-step skill creation tutorial - Best practices for semantic matching - Testing and validation workflows - Sharing skills with the community - Cross-platform compatibility notes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
TerminallyLazy committed
Dec 26, 2025 at 07:46 UTC
8693a9e6c6a3042adf5f23b23ccd9797aaaaef16
1 file changed
+468
docs/CONTRIBUTING-SKILLS.md
new
+468
@@ -0,0 +1,468 @@
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
+## Table of Contents
6
+
7
+- [What is a Skill?](#what-is-a-skill)
8
+- [Quick Start](#quick-start)
9
+- [SKILL.md Standard](#skillmd-standard)
10
+- [Creating Your First Skill](#creating-your-first-skill)
11
+- [Best Practices](#best-practices)
12
+- [Testing Skills](#testing-skills)
13
+- [Sharing Skills](#sharing-skills)
14
+- [Community Guidelines](#community-guidelines)
15
+
16
+---
17
+
18
+## What is a Skill?
19
+
20
+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.
21
+
22
+### Skills vs Tools vs Knowledge
23
+
24
+| Aspect | Skills | Tools | Knowledge |
25
+|--------|--------|-------|-----------|
26
+| **Loading** | Semantic recall | Always in prompt | Semantic recall |
27
+| **Purpose** | Procedures & expertise | Actions & functions | Facts & data |
28
+| **Format** | SKILL.md (YAML + Markdown) | Python/code | Text/documents |
29
+| **When to use** | "How to do X" | "Do X now" | "What is X" |
30
+
31
+### Cross-Platform Compatibility
32
+
33
+The SKILL.md standard is compatible with:
34
+- **Agent Zero** (this project)
35
+- **Claude Code** (Anthropic)
36
+- **Cursor** (AI IDE)
37
+- **OpenAI Codex CLI**
38
+- **GitHub Copilot**
39
+- **Goose** (Block)
40
+
41
+Skills you create here can be used in any of these platforms!
42
+
43
+---
44
+
45
+## Quick Start
46
+
47
+### Using the CLI (Recommended)
48
+
49
+```bash
50
+# Create a new skill interactively
51
+python -m python.helpers.skills_cli create my-skill-name
52
+
53
+# List all available skills
54
+python -m python.helpers.skills_cli list
55
+
56
+# Validate a skill
57
+python -m python.helpers.skills_cli validate my-skill-name
58
+
59
+# Search skills
60
+python -m python.helpers.skills_cli search "keyword"
61
+```
62
+
63
+### Manual Creation
64
+
65
+1. Create a folder in `skills/custom/` with your skill name
66
+2. Add a `SKILL.md` file with YAML frontmatter
67
+3. Optionally add supporting scripts (`.py`, `.sh`, `.js`)
68
+
69
+---
70
+
71
+## SKILL.md Standard
72
+
73
+Every skill must have a `SKILL.md` file with this structure:
74
+
75
+```markdown
76
+---
77
+name: "skill-name"
78
+description: "A clear, concise description of what this skill does and when to use it"
79
+version: "1.0.0"
80
+author: "Your Name <email@example.com>"
81
+license: "MIT"
82
+tags: ["category", "purpose", "technology"]
83
+triggers:
84
+ - "keyword that activates this skill"
85
+ - "another trigger phrase"
86
+allowed_tools:
87
+ - tool_name
88
+ - another_tool
89
+metadata:
90
+ complexity: "beginner|intermediate|advanced"
91
+ category: "development|devops|data|productivity|creative"
92
+ estimated_time: "5 minutes"
93
+---
94
+
95
+# Skill Name
96
+
97
+## Overview
98
+
99
+Brief description of what this skill accomplishes.
100
+
101
+## When to Use
102
+
103
+- Situation 1 where this skill applies
104
+- Situation 2 where this skill applies
105
+
106
+## Instructions
107
+
108
+### Step 1: First Step
109
+
110
+Detailed instructions...
111
+
112
+### Step 2: Second Step
113
+
114
+More instructions...
115
+
116
+## Examples
117
+
118
+### Example 1: Basic Usage
119
+
120
+\`\`\`python
121
+# Code example
122
+\`\`\`
123
+
124
+### Example 2: Advanced Usage
125
+
126
+\`\`\`python
127
+# Advanced code example
128
+\`\`\`
129
+
130
+## Common Pitfalls
131
+
132
+- Pitfall 1 and how to avoid it
133
+- Pitfall 2 and how to avoid it
134
+
135
+## Related Skills
136
+
137
+- [related-skill-1](../related-skill-1/SKILL.md)
138
+- [related-skill-2](../related-skill-2/SKILL.md)
139
+```
140
+
141
+### Required Fields
142
+
143
+| Field | Description |
144
+|-------|-------------|
145
+| `name` | Unique identifier (lowercase, hyphens allowed) |
146
+| `description` | What the skill does (used for semantic matching) |
147
+
148
+### Optional Fields
149
+
150
+| Field | Description |
151
+|-------|-------------|
152
+| `version` | Semantic version (e.g., "1.0.0") |
153
+| `author` | Your name and email |
154
+| `license` | License (MIT, Apache-2.0, etc.) |
155
+| `tags` | Categories for discovery |
156
+| `triggers` | Phrases that activate this skill |
157
+| `allowed_tools` | Tools this skill can use |
158
+| `metadata` | Additional structured data |
159
+
160
+---
161
+
162
+## Creating Your First Skill
163
+
164
+### Step 1: Identify the Need
165
+
166
+Ask yourself:
167
+- What expertise would help the agent?
168
+- When should this skill be activated?
169
+- What steps should the agent follow?
170
+
171
+### Step 2: Create the Structure
172
+
173
+```bash
174
+# Using CLI
175
+python -m python.helpers.skills_cli create my-awesome-skill
176
+
177
+# Or manually
178
+mkdir -p skills/custom/my-awesome-skill
179
+touch skills/custom/my-awesome-skill/SKILL.md
180
+```
181
+
182
+### Step 3: Write the SKILL.md
183
+
184
+```markdown
185
+---
186
+name: "my-awesome-skill"
187
+description: "Helps with [specific task] when [specific situation]"
188
+version: "1.0.0"
189
+author: "Your Name"
190
+tags: ["category"]
191
+---
192
+
193
+# My Awesome Skill
194
+
195
+## When to Use
196
+
197
+Use this skill when you need to [specific task].
198
+
199
+## Instructions
200
+
201
+1. First, do this...
202
+2. Then, do that...
203
+3. Finally, verify by...
204
+
205
+## Examples
206
+
207
+### Example: Basic Case
208
+
209
+[Show a complete example]
210
+```
211
+
212
+### Step 4: Add Supporting Files (Optional)
213
+
214
+If your skill needs scripts:
215
+
216
+```
217
+my-awesome-skill/
218
+├── SKILL.md # Required
219
+├── helper.py # Optional Python script
220
+├── setup.sh # Optional shell script
221
+└── templates/ # Optional templates folder
222
+ └── config.json
223
+```
224
+
225
+Reference them in your SKILL.md:
226
+
227
+```markdown
228
+## Scripts
229
+
230
+This skill includes helper scripts:
231
+- `helper.py` - Does X
232
+- `setup.sh` - Sets up Y
233
+```
234
+
235
+### Step 5: Test Your Skill
236
+
237
+```bash
238
+# Validate the skill
239
+python -m python.helpers.skills_cli validate my-awesome-skill
240
+
241
+# Test in Agent Zero
242
+# Start the agent and ask it to perform the task your skill handles
243
+```
244
+
245
+---
246
+
247
+## Best Practices
248
+
249
+### Writing Effective Descriptions
250
+
251
+The `description` field is crucial for semantic matching. Make it:
252
+
253
+**Good:**
254
+```yaml
255
+description: "Guides systematic debugging of Python applications using print statements, debugger, and logging to identify root causes"
256
+```
257
+
258
+**Bad:**
259
+```yaml
260
+description: "Helps with debugging"
261
+```
262
+
263
+### Structuring Instructions
264
+
265
+1. **Be Specific** - Avoid vague instructions
266
+2. **Use Steps** - Number your steps clearly
267
+3. **Include Examples** - Show, don't just tell
268
+4. **Anticipate Errors** - Include troubleshooting
269
+
270
+### Semantic Triggers
271
+
272
+Design your description and content so the skill is recalled when relevant:
273
+
274
+```yaml
275
+# Include synonyms and related terms
276
+description: "Helps create REST APIs, web services, HTTP endpoints, and backend routes using FastAPI, Flask, or Express"
277
+```
278
+
279
+### Keep Skills Focused
280
+
281
+One skill = one expertise area. If your skill is getting too long, split it:
282
+
283
+- `api-design` - API structure and patterns
284
+- `api-security` - API authentication and authorization
285
+- `api-testing` - API testing strategies
286
+
287
+---
288
+
289
+## Testing Skills
290
+
291
+### Local Testing
292
+
293
+1. **Validate Structure:**
294
+ ```bash
295
+ python -m python.helpers.skills_cli validate my-skill
296
+ ```
297
+
298
+2. **Test Semantic Recall:**
299
+ Start Agent Zero and ask questions that should trigger your skill.
300
+
301
+3. **Verify Instructions:**
302
+ Follow your own instructions manually to ensure they work.
303
+
304
+### Automated Testing
305
+
306
+Create a test file `test_skill.py` in your skill folder:
307
+
308
+```python
309
+"""Tests for my-awesome-skill"""
310
+import pytest
311
+from python.helpers.skills import SkillManager
312
+
313
+def test_skill_loads():
314
+ manager = SkillManager()
315
+ skill = manager.get_skill("my-awesome-skill")
316
+ assert skill is not None
317
+ assert skill.name == "my-awesome-skill"
318
+
319
+def test_skill_has_required_fields():
320
+ manager = SkillManager()
321
+ skill = manager.get_skill("my-awesome-skill")
322
+ assert skill.description
323
+ assert len(skill.description) > 20
324
+```
325
+
326
+---
327
+
328
+## Sharing Skills
329
+
330
+### Contributing to Agent Zero
331
+
332
+1. **Fork the Repository:**
333
+ ```bash
334
+ git clone https://github.com/agent0ai/agent-zero.git
335
+ cd agent-zero
336
+ ```
337
+
338
+2. **Create Your Skill:**
339
+ ```bash
340
+ python -m python.helpers.skills_cli create my-skill
341
+ # Edit skills/custom/my-skill/SKILL.md
342
+ ```
343
+
344
+3. **Move to Builtin (for contribution):**
345
+ ```bash
346
+ mv skills/custom/my-skill skills/builtin/my-skill
347
+ ```
348
+
349
+4. **Create a Pull Request:**
350
+ - Branch: `feat/skill-my-skill-name`
351
+ - Title: `feat(skills): add my-skill-name skill`
352
+ - Description: Explain what the skill does and why it's useful
353
+
354
+### Publishing to Skills Marketplace
355
+
356
+Share your skills on [skillsmp.com](https://skillsmp.com):
357
+
358
+1. Create a GitHub repository for your skill
359
+2. Ensure it follows the SKILL.md standard
360
+3. Submit to the marketplace via their contribution process
361
+
362
+### Creating a Skills Collection
363
+
364
+For multiple related skills, create a repository:
365
+
366
+```
367
+my-skills-collection/
368
+├── README.md
369
+├── skills/
370
+│ ├── skill-1/
371
+│ │ └── SKILL.md
372
+│ ├── skill-2/
373
+│ │ └── SKILL.md
374
+│ └── skill-3/
375
+│ └── SKILL.md
376
+└── LICENSE
377
+```
378
+
379
+---
380
+
381
+## Community Guidelines
382
+
383
+### Quality Standards
384
+
385
+- **Tested** - Skills must be tested before submission
386
+- **Documented** - Clear instructions and examples
387
+- **Focused** - One expertise per skill
388
+- **Original** - Don't duplicate existing skills
389
+
390
+### Naming Conventions
391
+
392
+- Use lowercase with hyphens: `my-skill-name`
393
+- Be descriptive: `python-debugging` not `debug`
394
+- Avoid generic names: `fastapi-crud` not `api`
395
+
396
+### License
397
+
398
+- Include a license (MIT recommended for maximum compatibility)
399
+- Respect licenses of any code you include
400
+- Don't include proprietary or copyrighted content
401
+
402
+### Code of Conduct
403
+
404
+- Be respectful in all interactions
405
+- Provide constructive feedback
406
+- Help newcomers learn
407
+- Report issues responsibly
408
+
409
+---
410
+
411
+## Resources
412
+
413
+### Official Documentation
414
+
415
+- [Agent Zero Documentation](./README.md)
416
+- [Architecture Guide](./architecture.md)
417
+- [Skills System](./architecture.md#skills-system)
418
+
419
+### Community
420
+
421
+- [GitHub Issues](https://github.com/agent0ai/agent-zero/issues)
422
+- [Discussions](https://github.com/agent0ai/agent-zero/discussions)
423
+
424
+### External Resources
425
+
426
+- [Skills Marketplace](https://skillsmp.com)
427
+- [Awesome Agent Skills](https://github.com/skillmatic-ai/awesome-agent-skills)
428
+- [Anthropic Skills Repository](https://github.com/anthropics/skills)
429
+
430
+---
431
+
432
+## FAQ
433
+
434
+### Q: Where should I put my skills?
435
+
436
+**A:** During development, use `skills/custom/`. For contribution, move to `skills/builtin/`.
437
+
438
+### Q: How are skills discovered?
439
+
440
+**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.
441
+
442
+### Q: Can I use skills from other platforms?
443
+
444
+**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/`.
445
+
446
+### Q: How do I update a skill?
447
+
448
+**A:** Edit the SKILL.md file and increment the version number. Changes take effect on agent restart.
449
+
450
+### Q: Can skills call other skills?
451
+
452
+**A:** Skills don't directly call each other, but the agent may combine multiple skills when appropriate for a task.
453
+
454
+---
455
+
456
+## Example Skills to Learn From
457
+
458
+Check out these well-structured skills in `skills/builtin/`:
459
+
460
+- `brainstorming/` - Requirements exploration workflow
461
+- `debugging/` - Systematic debugging methodology
462
+- `tdd/` - Test-driven development process
463
+- `code_review/` - Comprehensive review checklist
464
+- `create_skill/` - Meta-skill for creating new skills
465
+
466
+---
467
+
468
+Happy skill building! 🚀