1---
2name: skill-forge
3description: Write or improve an LLM agent skill. Use when user says "create skill", "write a skill", "improve this skill", "new skill", "skill for X", or wants to build a SKILL.md file.
4disable-model-invocation: true
5argument-hint: "[skill name or path to existing SKILL.md]"
6---
7
8# Skill Forge
9
10Generate or improve skills for LLM agent tools (Claude Code, Cursor, Crush, and any SKILL.md-compatible system). Research-backed, based on official docs, plugin source, and real-world skill audits.
11
12## When to Use
13
14- Creating a new skill from scratch
15- Improving an existing skill's description, structure, or settings
16- Auditing a skill for common mistakes
17- Deciding between rule vs skill vs CLAUDE.md for a piece of context
18
19## Step 1: Understand the Request
20
21If $ARGUMENTS points to an existing SKILL.md, read it first. Otherwise, ask:
22
231. **What does it do?** - the core capability or workflow
242. **Who triggers it?** - user only (`disable-model-invocation: true`), model auto (`default`), or background (`user-invocable: false`)
253. **Side effects?** - does it commit, deploy, send messages, modify state?
264. **Scope?** - personal (`~/.<agent>/skills/`), project (`.<agent>/skills/`), or plugin?
27
28## Step 2: Choose the Right Mechanism
29
30These paths use `.claude/` as example but apply to any agent that supports SKILL.md format (Crush, Cursor, etc.):
31
32| Put here | When |
33|----------|------|
34| CLAUDE.md / agent config | Rule applies to ALL work, every session, short |
35| `.<agent>/rules/` | Applies only when touching specific file types (use `paths` frontmatter) |
36| `.<agent>/skills/` | On-demand workflow, detailed reference, or behavioral mode |
37
38Don't make a skill when a rule or CLAUDE.md line would suffice.
39
40## Step 3: Write the Frontmatter
41
42### Required fields
43
44```yaml
45---
46name: skill-name # lowercase, hyphens, max 64 chars
47description: ... # THE most important field. See below.
48---
49```
50
51### Optional fields
52
53| Field | Use when |
54|-------|----------|
55| `disable-model-invocation: true` | Side effects (commits, deploys), behavioral modes, timing-sensitive workflows |
56| `user-invocable: false` | Background knowledge Claude should absorb passively |
57| `argument-hint: "[hint]"` | Skill takes input - shows in autocomplete |
58| `allowed-tools: Read, Grep` | Restrict or pre-approve tools |
59| `context: fork` | Run in isolated subagent (research, batch ops, analysis) |
60| `agent: Explore` | Subagent type when using `context: fork` |
61
62### Invocation matrix
63
64| Setting | User invokes | Claude invokes | Description in context |
65|---------|-------------|---------------|----------------------|
66| (default) | yes | yes | yes |
67| `disable-model-invocation: true` | yes | no | no |
68| `user-invocable: false` | no | yes | yes |
69
70**Key insight:** with `disable-model-invocation: true`, the description is NOT in context at all. Don't over-optimize the description - write it for your own docs reference only.
71
72## Step 4: Write the Description
73
74The description is what Claude pattern-matches against to decide whether to load the skill. There is NO algorithmic routing - Claude's language model reads all descriptions and semantically matches.
75
76### Formula
77
781. **What it does** - one sentence, outcome-first
792. **Trigger phrases** - exact words: "Use when user says X, Y, Z"
803. **Anti-triggers** - "NOT for..." if false positives are a risk
814. **Prerequisites** - required setup if any
82
83### Rules
84
85- Under 60 words
86- Every word costs token budget (2% of context window shared across ALL skill descriptions)
87- Description handles matching only - body handles instructions
88- Don't repeat body content in description
89- Be slightly "pushy" - Claude undertriggers by default
90
91### Good example
92
93> "Translates Figma designs into production-ready code with 1:1 visual fidelity. Use when implementing UI from Figma files, when user mentions 'implement design', 'generate code', 'build Figma design', or provides Figma URLs. Requires Figma MCP server connection."
94
95### Bad example
96
97> "Use when user wants to plan something" - too vague, false positives everywhere.
98
99## Step 5: Write the Body
100
101### Structure
102
103```markdown
104# Skill Title
105
106Brief context sentence.
107
108## When to Use
109(if not covered by description)
110
111## Process / Steps
1121. Step one
1132. Step two
114
115## Rules / Constraints
116- Rule one
117- Rule two
118
119## Examples (if applicable)
120Show patterns Claude should follow.
121
122## Validation / Checklist (if applicable)
123How to verify output quality.
124```
125
126### Rules
127
128- **Under 500 lines.** Full SKILL.md loads into context when invoked. Move reference material to supporting files.
129- **Use $ARGUMENTS** if the skill takes input. Without it, Claude Code appends `ARGUMENTS: <value>` at the end which is messier.
130- **Numbered lists** for sequential steps, bullets for options/rules.
131- **Bold critical constraints** with `**IMPORTANT:**`.
132- **Say "do not skip steps"** explicitly when order matters.
133- **H2 for major sections, H3 for sub-sections.** Max 2 heading levels.
134
135### Supporting files
136
137Put adjacent to SKILL.md in the skill directory:
138- `examples.md` - example inputs/outputs
139- `reference.md` - detailed reference docs
140- `scripts/helper.sh` - executable scripts
141
142Reference them from SKILL.md so Claude knows to load them. Files not accessed consume zero tokens.
143
144### Dynamic content injection
145
146Skills support shell command output injection with `!` prefix:
147- `!`\`git branch --show-current\` - inject current branch
148- `!`\`ls src/\` - inject file listing
149
150Use for context that changes between invocations.
151
152## Step 6: Validate
153
154Run this checklist on the generated skill:
155
156- [ ] Description under 60 words
157- [ ] Description is trigger-focused (what/when), not instruction-focused (how)
158- [ ] Body under 500 lines
159- [ ] No duplication between description and body
160- [ ] Correct invocation setting for the use case (side effects = `disable-model-invocation: true`)
161- [ ] `$ARGUMENTS` used if skill takes input
162- [ ] No vague trigger phrases that cause false positives
163- [ ] No `context: fork` on reference-only content (subagent gets instructions with no task)
164- [ ] Critical constraints are bolded
165- [ ] Steps are numbered when order matters
166- [ ] Supporting files referenced if body would exceed 500 lines
167
168## Common Mistakes
169
1701. **Vague descriptions** - "Use when user wants to plan" triggers on everything
1712. **Missing `disable-model-invocation: true` on side-effect skills** - Claude will auto-commit, auto-deploy
1723. **Body too long** - 500+ lines burns context. Split into supporting files.
1734. **Redundant description + body** - description matches, body instructs. Don't duplicate.
1745. **`context: fork` on reference content** - subagent gets instructions with no actionable task
1756. **Over-explaining in description** - the description isn't the instructions
1767. **Missing NOT conditions** - for behavioral modes, add explicit "NEVER activate unless..."
1778. **`user-invocable: false` on things users should manually trigger** - confusing