paultyng/skill-issue / skills/create-skill
create-skill
VerifiedUse when creating, writing, or authoring a new Cursor agent skill, or when asking about skill structure, SKILL.md format, or skill best practices.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.5 KB |
| best-practices.md | markdown | 13.1 KB |
SKILL.md
View on GitHub---
name: create-skill
description: Use when creating, writing, or authoring a new Cursor agent skill, or when asking about skill structure, SKILL.md format, or skill best practices.
---
# Create Skill
## Skill Types
Categorize before writing -- this determines structure, degrees of freedom, and testing approach:
- **Technique**: concrete method with steps (e.g. condition-based-waiting)
- **Pattern**: mental model / way of thinking (e.g. flatten-with-flags)
- **Reference**: API docs, syntax guides, tool documentation
- **Workflow**: multi-step process with decision points (e.g. ship-it)
## Requirements Gathering
Infer from conversation context when possible. If clarification is needed, use AskQuestion (or ask conversationally if unavailable). Capture:
1. **Purpose and scope**: what specific task or workflow
2. **Storage location**: personal (`~/.cursor/skills/`) or project (`.cursor/skills/`)
3. **Trigger scenarios**: when should the agent apply this skill
4. **Domain knowledge**: what the agent wouldn't already know
5. **Output format**: templates, styles, or conventions required
6. **Existing patterns**: examples or conventions to follow
## Design
### Name
- Lowercase letters, numbers, hyphens only. Max 64 chars
- Prefer verb-first or gerund form: `create-skill` > `skill-creation`, `analyze-sessions` > `session-analysis`
- Name by what you DO or core insight, not generic labels
- Avoid: `helper`, `utils`, `tools`, `misc`
### Description (CSO-Critical)
The description determines whether the agent loads this skill. Max 1024 chars, third person.
**Start with "Use when..."** -- describe ONLY triggering conditions (symptoms, situations, contexts).
**NEVER summarize the skill's workflow or process.** Testing shows agents follow descriptions as shortcuts, skipping the full skill body. A description saying "does X then Y" causes agents to do exactly X then Y without reading the actual detailed instructions.
Include concrete triggers: error messages, symptoms, tool names, synonyms.
```yaml
# BAD: workflow summary -- agent will shortcut to this
description: Analyzes code diffs, generates commit messages, and pushes to remote.
# BAD: too vague
description: Helps with documents.
# GOOD: triggering conditions only
description: Use when reviewing pull requests, examining code changes, or when asked for a code review.
# GOOD: specific triggers with keywords
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently.
```
### Directory Layout
```
skill-name/
├── SKILL.md # Required -- main instructions
├── reference.md # Optional -- detailed docs (progressive disclosure)
└── scripts/ # Optional -- utility scripts
└── validate.py
```
## Authoring Principles
Express requirement levels in skill instructions with RFC 2119 key words (`MUST` / `SHOULD` / `MAY`), sparingly and only where the level matters. See the `normative-language` rule.
### Conciseness
The context window is shared. Only add what the agent doesn't already know. Challenge each paragraph: "Does this justify its token cost?"
```markdown
# GOOD (~50 tokens): assumes agent knows what PDFs are
## Extract PDF text
Use pdfplumber:
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
# BAD (~150 tokens): explains what a PDF is
PDF (Portable Document Format) files are a common file format...
```
### Progressive Disclosure
Keep SKILL.md under 500 lines. Put detailed reference material in separate files the agent reads only when needed. Keep references **one level deep** from SKILL.md -- deeply nested references may be partially read.
```markdown
## Advanced features
**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
```
For reference files over 100 lines, include a table of contents at the top.
### Degrees of Freedom
Match specificity to task fragility:
- **High freedom** (text instructions): multiple valid approaches, context-dependent. Example: code review guidelines
- **Medium freedom** (pseudocode/templates): preferred pattern with acceptable variation. Example: report generation
- **Low freedom** (exact scripts): fragile operations, consistency critical. Example: database migrations -- "Run exactly this. Do not modify."
### Token Efficiency
- Move details to `--help` flags or reference files
- Cross-reference other skills instead of repeating content
- One excellent example beats many mediocre ones
- Compress examples: show minimal input/output, not verbose narratives
## Common Patterns
Brief summary below. See [best-practices.md](best-practices.md) for detailed examples with good/bad comparisons.
- **Template**: provide output format templates (strict for APIs, flexible for analysis)
- **Examples**: input/output pairs showing desired style and detail level
- **Workflow/Checklist**: sequential steps with copy-paste progress checklist
- **Conditional workflow**: decision points guiding to different paths
- **Feedback loop**: validate → fix → re-validate cycle for quality-critical tasks
## Script Guidelines
When including utility scripts:
- **Solve, don't punt**: handle errors explicitly instead of failing and letting the agent figure it out
- **Self-documenting constants**: no magic numbers -- comment why each value was chosen
- **Clear intent**: state whether the agent should **execute** the script ("Run `analyze.py`") or **read** it as reference ("See `analyze.py` for the algorithm")
- Pre-made scripts are more reliable than generated code, save tokens, and ensure consistency
## MCP Tool References
Always use fully qualified names: `ServerName:tool_name`
```markdown
Use the GitHub:create_issue tool to create issues.
Use the Atlassian:getJiraIssueTypeMetaWithFields tool to discover custom fields.
```
## External Content and Licensing
When incorporating content from web sources or OSS into a skill:
- **Inline the content** -- skills should be self-contained with no runtime web lookups
- **Always cite the source URL** even when content is fully inlined
- **Comply with licensing terms**: MIT/Apache/etc. require copyright notice preserved
- Include a **Sources** section in the skill with attribution and license type
- For OSS: link to the repo/file, note the license, credit the author(s)
- For web content (docs, blog posts): link to the source URL for reference
## Testing and Validation
Skills are TDD applied to process documentation. If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
### RED -- Baseline
Run a representative scenario WITHOUT the skill. Document:
- What choices did the agent make?
- What rationalizations did it use (verbatim)?
- Which pressures triggered violations?
### GREEN -- Write Minimal Skill
Write the skill addressing those specific failures. Run the same scenario WITH the skill. The agent should now comply.
### REFACTOR -- Close Loopholes
Agent found a new rationalization? Add an explicit counter. Re-test until the skill is robust.
### Testing by Skill Type
- **Discipline-enforcing** (rules/requirements): pressure scenarios combining time + sunk cost + exhaustion
- **Technique** (how-to guides): application scenarios + edge cases + missing-information tests
- **Pattern** (mental models): recognition scenarios + counter-examples (when NOT to apply)
- **Reference** (documentation): retrieval scenarios + application scenarios + gap testing
### Bulletproofing Discipline Skills
For skills that enforce rules, agents will rationalize under pressure:
- Don't just state the rule -- forbid specific workarounds
- Build a rationalization table: `| Excuse | Reality |`
- Create a red flags list for self-checking
- Address "spirit vs letter" arguments: "Violating the letter of the rules IS violating the spirit"
## Verification Checklist
Before finalizing:
- [ ] Description starts with "Use when..." -- triggering conditions only, no workflow summary
- [ ] SKILL.md body is under 500 lines
- [ ] Consistent terminology throughout (pick one term, use it everywhere)
- [ ] File references are one level deep from SKILL.md
- [ ] No time-sensitive information (use "old patterns" section if needed)
- [ ] Examples are concrete, not abstract
- [ ] Tested with a representative scenario (baseline → with skill)
- [ ] External content is inlined with source attribution
## Anti-Patterns
- **Narrative storytelling**: "In session 2025-10-03, we found..." -- too specific, not reusable
- **Multi-language dilution**: one excellent example in the most relevant language beats mediocre examples in five languages
- **Workflow summary in description**: causes agents to shortcut past the actual skill body
- **Generic labels**: helper1, step3, pattern4 -- labels should have semantic meaning
- **Windows-style paths**: always use forward slashes (`scripts/helper.py`)
- **Too many options**: provide a default with an escape hatch, not a menu of five libraries
- **Vague names**: `helper`, `utils`, `tools` -- name by what the skill does
- **Inconsistent terminology**: pick one term (e.g. always "API endpoint", not mixing "URL", "route", "path")
---
## Sources
Content in this skill and [best-practices.md](best-practices.md) incorporates material from:
- [Anthropic: Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
- [obra/superpowers: writing-skills](https://github.com/obra/superpowers/blob/main/skills/writing-skills/SKILL.md) -- used under [MIT License](https://github.com/obra/superpowers/blob/main/LICENSE), copyright Jesse Vincent
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |