productivity / Work & communicate
write-a-skill
Create new agent skills with proper structure, progressive disclosure, and bundled resources.
Put it to work.
Ask your agent to use write-a-skill, or let it load the skill when your task matches the description.
Use the write-a-skill skillInvocation syntax varies by agent. Use the skill name in your prompt, or your agent’s supported slash command.
About this skill
Create new agent skills with proper structure, progressive disclosure, and bundled resources. Useful when you want to add a new entry to this repo, or to build skills for any other agent that consumes the SKILL.md format.
Flow
flowchart LR
G[Gather requirements] --> D[Draft skill]
D --> R[Review with user]
R -->|revisions| D
R -->|approved| F[Final skill]Skill structure the skill produces
skill-name/
├── SKILL.md # main instructions (required)
├── REFERENCE.md # detailed docs (if needed)
├── EXAMPLES.md # usage examples (if needed)
└── scripts/ # utility scripts (if needed)
└── helper.jsSKILL.md should stay under ~100 lines; spill into REFERENCE/EXAMPLES files
when content gets large or rarely-needed. The frontmatter description is the
only thing the agent sees when deciding whether to load the skill — make it
specific.
Install
npx skills@latest add smeltery/skillsOr copy just this skill:
mkdir -p ~/.claude/skills/write-a-skill
curl -fsSL https://raw.githubusercontent.com/smeltery/skills/main/skills/productivity/write-a-skill/SKILL.md \
-o ~/.claude/skills/write-a-skill/SKILL.mdUsage
Trigger by saying "write a skill", "create a skill", or "build a skill".
Files
SKILL.md— canonical skill definition.
Attribution
Ported from mattpocock/skills under MIT. See THIRD_PARTY_LICENSES.md.
Read the full SKILL.md
Writing Skills
Process
Gather requirements - ask user about:
- What task/domain does the skill cover?
- What specific use cases should it handle?
- Does it need executable scripts or just instructions?
- Any reference materials to include?
Draft the skill - create:
- SKILL.md with concise instructions
- Additional reference files if content exceeds 500 lines
- Utility scripts if deterministic operations needed
Review with user - present draft and ask:
- Does this cover your use cases?
- Anything missing or unclear?
- Should any section be more/less detailed?
Skill Structure
skill-name/
├── SKILL.md # Main instructions (required)
├── REFERENCE.md # Detailed docs (if needed)
├── EXAMPLES.md # Usage examples (if needed)
└── scripts/ # Utility scripts (if needed)
└── helper.jsSKILL.md Template
---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---
# Skill Name
## Quick start
[Minimal working example]
## Workflows
[Step-by-step processes with checklists for complex tasks]
## Advanced features
[Link to separate files: See [REFERENCE.md](REFERENCE.md)]Description Requirements
The description is the only thing your agent sees when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
Goal: Give your agent just enough info to know:
- What capability this skill provides
- When/why to trigger it (specific keywords, contexts, file types)
Format:
- Max 1024 chars
- Write in third person
- First sentence: what it does
- Second sentence: "Use when [specific triggers]"
Good example:
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.Bad example:
Helps with documents.The bad example gives your agent no way to distinguish this from other document skills.
When to Add Scripts
Add utility scripts when:
- Operation is deterministic (validation, formatting)
- Same code would be generated repeatedly
- Errors need explicit handling
Scripts save tokens and improve reliability vs generated code.
When to Split Files
Split into separate files when:
- SKILL.md exceeds 100 lines
- Content has distinct domains (finance vs sales schemas)
- Advanced features are rarely needed
Review Checklist
After drafting, verify:
- Description includes triggers ("Use when...")
- SKILL.md under 100 lines
- No time-sensitive info
- Consistent terminology
- Concrete examples included
- References one level deep