tomimor Create & Audit Skills
Skills are markdown files that teach the agent specialized workflows. This skill covers both creating new ones and auditing existing ones.
Before You Begin: Gather Requirements
Before creating a skill, gather:
- Purpose and scope: What task or workflow does this skill handle?
- Target location: Personal (
~/.cursor/skills/) or project (.cursor/skills/)? - Trigger scenarios: When should the agent apply this skill?
- Key domain knowledge: What does the agent need that it wouldn't already know?
- Output format: Any required templates, formats, or styles?
- Existing patterns: Conventions or examples to follow?
Verbatim text from the user
If the user includes exact wording, use it verbatim in SKILL.md. Do not paraphrase, soften, or expand their copy.
Inferring from context
If conversation context exists, infer the skill from what was discussed — workflows, patterns, or domain knowledge that emerged.
Gathering information
Use AskQuestion for structured gathering:
- "Where should this skill be stored?" → ["Personal (~/.cursor/skills/)", "Project (.cursor/skills/)"]
- "Should this skill include executable scripts?" → ["Yes", "No"]
Auditing an Existing Skill
When auditing a skill, run the Summary Checklist (bottom of this file) against it and report:
Report format
| Severity | Meaning |
|---|---|
| Must fix | Violates core quality rules (broken frontmatter, over line limit, missing WHAT/WHEN) |
| Should fix | Hurts discoverability or wastes tokens (vague description, redundant sections) |
| Nice to have | Polish (could extract to reference file, terminology tweak) |
For each finding:
- State the problem in one line
- Cite the specific lines or section
- Suggest a concrete fix
End with a summary table of all findings by severity.
Skill File Structure
Directory layout
skill-name/
├── SKILL.md # Required - main instructions
├── reference.md # Optional - detailed docs
├── examples.md # Optional - usage examples
└── scripts/ # Optional - utility scripts
Storage locations
| Type | Path | Scope |
|---|---|---|
| Personal | ~/.cursor/skills/skill-name/ |
All your projects |
| Project | .cursor/skills/skill-name/ |
Shared via repository |
SKILL.md structure
---
name: your-skill-name
description: Brief description of what this skill does and when to use it
---
# Your Skill Name
## Instructions
Clear, step-by-step guidance for the agent.
## Examples
Concrete examples of using this skill.
Required metadata
| Field | Requirements | Purpose |
|---|---|---|
name |
Max 64 chars, lowercase letters/numbers/hyphens | Unique identifier |
description |
Max 1024 chars, non-empty | Discovery and auto-invocation |
Writing Effective Descriptions
The description drives skill discovery. Include both WHAT (capabilities) and WHEN (trigger scenarios).
Format
- Max 1024 chars, third person
- First sentence: what the skill does
- Second sentence:
Use when [specific triggers] - Trigger signals can include keywords, contexts, and file types (e.g. PDFs, .csv, Dockerfiles)
Best practices
Third person — the description is injected into the system prompt:
- Good: "Processes Excel files and generates reports"
- Bad: "I can help you process Excel files"
Specific trigger terms:
- Good: "Extract text from PDF files, fill forms, merge documents. Use when working with PDFs or document extraction."
- Bad: "Helps with documents"
Examples
description: Generate commit messages by analyzing git diffs. Use when writing commit messages or reviewing staged changes.
description: Review code for quality, security, and best practices. Use when reviewing pull requests or code changes.
Core Authoring Principles
1. Concise is key
The context window is shared. Every token competes for space.
The agent is already smart. Only add context it doesn't have. Challenge each paragraph: "Does this justify its token cost?"
# Good
Use pdfplumber for text extraction:
\`\`\`python
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
\`\`\`
# Bad
PDF (Portable Document Format) files are a common file format...
there are many libraries available... we recommend pdfplumber
because it's easy to use...
2. Keep SKILL.md under 500 lines
Extract detailed reference material into separate files.
3. Progressive disclosure
Essential info in SKILL.md. Detailed reference in linked files the agent reads only when needed.
## Additional resources
- For pattern examples, see [patterns.md](patterns.md)
Keep references one level deep. Deeply nested references get partially read.
4. Degrees of freedom
| Freedom | When | Example |
|---|---|---|
| High (text) | Multiple valid approaches | Code review guidelines |
| Medium (pseudocode) | Preferred pattern with wiggle room | Report generation |
| Low (scripts) | Fragile ops, consistency critical | Database migrations |
Anti-Patterns
1. Too many options
# Bad
"You can use pypdf, or pdfplumber, or PyMuPDF..."
# Good
"Use pdfplumber. For scanned PDFs needing OCR, use pdf2image + pytesseract."
2. Time-sensitive information
Don't tie instructions to dates. Use a "deprecated" section if needed.
3. Inconsistent terminology
Pick one term and stick with it: always "endpoint" (not mixing "URL", "route", "path").
4. Vague skill names
- Good:
processing-pdfs,analyzing-spreadsheets - Bad:
helper,utils,tools
5. Windows-style paths
Always use forward slashes: scripts/helper.py
When to Add Scripts
Add utility scripts when:
- The operation is deterministic (validation, formatting, parsing)
- The same code would be regenerated every run
- Errors need explicit, consistent handling
Scripts save tokens (no code in context) and improve reliability vs. generated code. For pattern examples, see patterns.md.
Skill Creation Workflow
Phase 1: Discovery
Gather:
- Purpose and primary use case
- Storage location (personal vs project)
- Trigger scenarios
- Requirements or constraints
- Existing examples or patterns
Phase 2: Design
- Draft the skill name (lowercase, hyphens, max 64 chars)
- Write a specific, third-person description
- Outline main sections
- Identify if supporting files or scripts are needed
Phase 3: Implementation
- Create the directory structure
- Write SKILL.md with frontmatter
- Create supporting reference files if needed
- Create utility scripts if needed
Phase 4: Review with the user
Present the draft and ask:
- Does this cover your use cases?
- Anything missing or unclear?
- Should any section be more or less detailed?
Apply feedback before running the verification checklist.
Phase 5: Verification
Run the Summary Checklist below. Fix anything that fails before delivering.
Common Patterns
For pattern examples and a complete skill template, see patterns.md.
Summary Checklist
Before finalizing any skill (creation or audit), verify:
Core quality
- Description is specific and includes trigger terms
- Description includes both WHAT and WHEN
- Description follows two-sentence format (what / "Use when...")
- Written in third person
- SKILL.md body is under 500 lines
- Consistent terminology throughout
- Examples are concrete, not abstract
Structure
- File references are one level deep
- Progressive disclosure used appropriately
- Workflows have clear steps
- No time-sensitive information
If including scripts
- Scripts solve problems rather than punt
- Required packages are documented
- Error handling is explicit and helpful
- No Windows-style paths