SKILL.md
When to Create a Skill
Create a skill when:
- A pattern is used repeatedly and AI needs guidance
- Project-specific conventions differ from generic best practices
- Complex workflows need step-by-step instructions
- Decision trees help AI choose the right approach
Don't create a skill when:
- Documentation already exists (create a reference instead)
- Pattern is trivial or self-explanatory
- It's a one-off task
Skill Structure
skills/{skill-name}/
├── SKILL.md # Required - main skill file
├── assets/ # Optional - templates, schemas, examples
│ ├── template.py
│ └── schema.json
└── references/ # Optional - links to local docs
└── docs.md # Points to docs/developer-guide/*.mdxSKILL.md Template
---
name: {skill-name}
description: >
{One-line description of what this skill does}.
Trigger: {When the AI should load this skill}.
license: Apache-2.0
metadata:
author: gentleman-programming
version: "1.0"
---
## When to Use
{Bullet points of when to use this skill}
## Critical Patterns
{The most important rules - what AI MUST know}
## Code Examples
{Minimal, focused examples}
## Commands
{Common commands}
## Resources
- **Templates**: See [assets/](assets/) for {description}
- **Documentation**: See [references/](references/) for local docsNaming Conventions
| Type | Pattern | Examples |
|---|---|---|
| Generic skill | {technology} |
pytest, playwright, typescript |
| Project-specific | {project}-{component} |
myapp-api, myapp-ui |
| Testing skill | {project}-test-{component} |
myapp-test-sdk, myapp-test-api |
| Workflow skill | {action}-{target} |
skill-creator, jira-task |
Decision: assets/ vs references/
Need code templates? → assets/
Need JSON schemas? → assets/
Need example configs? → assets/
Link to existing docs? → references/
Link to external guides? → references/ (with local path)Key Rule: references/ should point to LOCAL files, not web URLs.
Frontmatter Fields
| Field | Required | Description |
|---|---|---|
name |
Yes | Skill identifier (lowercase, hyphens) |
description |
Yes | What + Trigger in one block |
license |
Yes | Always Apache-2.0 |
metadata.author |
Yes | gentleman-programming |
metadata.version |
Yes | Semantic version as string |
Content Guidelines
DO
- Start with the most critical patterns
- Use tables for decision trees
- Keep code examples minimal and focused
- Include Commands section with copy-paste commands
DON'T
- Add Keywords section (agent searches frontmatter, not body)
- Duplicate content from existing docs (reference instead)
- Include lengthy explanations (link to docs)
- Add troubleshooting sections (keep focused)
- Use web URLs in references (use local paths)
Registering the Skill
After creating the skill, add it to AGENTS.md:
| `{skill-name}` | {Description} | [SKILL.md](skills/{skill-name}/SKILL.md) |Checklist Before Creating
- Skill doesn't already exist (check
skills/) - Pattern is reusable (not one-off)
- Name follows conventions
- Frontmatter is complete (description includes trigger keywords)
- Critical patterns are clear
- Code examples are minimal
- Commands section exists
- Added to AGENTS.md
Resources
- Templates: See [assets/](assets/) for SKILL.md template