azat-io Creating Skills
Skills are reference guides for proven techniques, patterns, or tools. They help AI agents find and apply effective approaches.
When to Create
- Technique wasn't intuitively obvious
- Pattern applies broadly (not project-specific)
- Would reference this again across projects
Skip if: one-off solution, project-specific convention (→ put in CLAUDE.md), or well-documented elsewhere.
Skill Types
| Type | Purpose | Example |
|---|---|---|
| Technique | Concrete method with steps | discovering, researching |
| Pattern | Way of thinking about problems | creating-subagents |
| Reference | API docs, syntax guides | tool documentation |
File Structure
skills/
skill-name/
skill.md # Main reference (required)
*.md # Supporting files if needed
skill.md Structure
---
name: skill-name
description: [What it does]. Use when [specific triggering conditions].
---
# Skill Name
## Overview
What is this? Core principle in 1-2 sentences.
## When to Use
- Symptoms, situations, triggers
- When NOT to use
## Quick Reference
Table or bullets for scanning.
## Core Pattern
Main technique or approach.
## Delegate (if applicable)
Which agents/subagents to use and when.
## Common Mistakes
What goes wrong + fixes.
Description Rules
Description = What It Does + When to Use It
Write in third person: one clause for the capability, then the triggers.
# ❌ BAD: Retells the workflow step by step
description:
Frame the problem, collect signals, compare 2-3 options, write a brief.
# ❌ BAD: Too vague
description: For research tasks.
# ❌ BAD: Triggers only, no capability signal
description: Use when requirements are fuzzy or multiple approaches exist.
# ✅ GOOD: Capability + triggering conditions
description:
Evaluate technical options with evidence and choose an approach. Use when
requirements are fuzzy or multiple approaches exist.
Why: The description is the only signal AI uses to pick a skill among many — without a capability summary, routing degrades. Keep the capability to one clause: if it retells the workflow, AI may follow the description instead of reading the full skill content.
Naming
- Lowercase with hyphens:
creating-skills - Gerunds for processes:
discovering,researching,creating-subagents - Verb-first, active voice
Design Process
1. Define the Problem
Before writing:
- What technique/pattern does this teach?
- When should AI use this skill?
- What are the triggering symptoms?
2. Write Description First
Description determines when skill is loaded. Write it before content.
3. Minimal Content
- Start with the smallest skill that works
- Add sections only when needed
- Tables > prose for reference material
4. Test Before Deploy
Run scenarios where skill should activate:
- Does AI find the skill?
- Does AI follow the technique correctly?
- Are there gaps or ambiguities?
5. Iterate
When skill fails, identify the gap and fix.
Common Mistakes
| Mistake | Fix |
|---|---|
| Description retells workflow | One capability clause + triggers |
| Too much content | Minimal, scannable, tables |
| Narrative storytelling | Structured reference format |
| Project-specific rules | Put in CLAUDE.md instead |
| No "When to Use" section | Always include triggers and skip conditions |
| Generic labels in examples | Semantic, meaningful names |
Cross-References
Reference other skills by name:
# ✅ Good
**Prerequisites:** Use **discovering** skill first.
# ❌ Bad: force-loads file
@skills/discovering/skill.md
Creation Checklist
- Problem clearly defined
- Description states capability, then "Use when..." triggers
- Description has no step-by-step workflow
- Name uses gerund for processes
- When to Use section with triggers and skip conditions
- Quick Reference for scanning
- Common Mistakes section
- Delegate section if skill uses agents or subagents
- Pipeline navigation (what comes before/after), if part of a pipeline
- Tested on real scenario