KunanonJ Creating Skills in Cursor
This skill guides you through creating effective Agent Skills for Cursor. Skills are markdown files that teach the agent how to perform specific tasks.
Before You Begin: Gather Requirements
- Purpose and scope: What specific task or workflow should this skill help with?
- Target location: Personal skill (~/.cursor/skills/) or project skill (.cursor/skills/)?
- Trigger scenarios: When should the agent automatically apply this skill?
- Key domain knowledge: What specialized information does the agent need?
- Output format preferences: Are there specific templates or formats required?
- Existing patterns: Are there existing examples or conventions to follow?
Skill File Structure
Directory Layout
skill-name/
├── SKILL.md # Required - main instructions
├── reference.md # Optional - detailed documentation
├── examples.md # Optional - usage examples
└── scripts/ # Optional - utility scripts
├── validate.py
└── helper.sh
Storage Locations
| Type | Path | Scope |
|---|---|---|
| Personal | ~/.cursor/skills/skill-name/ | Available across all your projects |
| Project | .cursor/skills/skill-name/ | Shared with anyone using the repository |
IMPORTANT: Never create skills in ~/.cursor/skills-cursor/. This directory is reserved for Cursor's internal built-in skills.
SKILL.md Structure
---
name: your-skill-name
description: Brief description of what this skill does and when to use it
disable-model-invocation: true
---
# Your Skill Name
## Instructions
Clear, step-by-step guidance for the agent.
## Examples
Concrete examples of using this skill.
Default disable-model-invocation: true so the skill only loads when named explicitly.
Required Metadata Fields
| Field | Requirements | Purpose |
|---|---|---|
name |
Max 64 chars, lowercase letters/numbers/hyphens only | Unique identifier |
description |
Max 1024 chars, non-empty | Helps agent decide when to apply |
Writing Effective Descriptions
- Write in third person: "Processes Excel files and generates reports"
- Be specific and include trigger terms: Include both WHAT and WHEN
- Include trigger scenarios: "Use when working with PDF files or when the user mentions PDFs"
Core Authoring Principles
1. Concise is Key
The context window is shared. Every token competes for space. Only add context the agent doesn't already have.
2. Keep SKILL.md Under 500 Lines
Use progressive disclosure for detailed content.
3. Progressive Disclosure
Put essential information in SKILL.md; detailed reference material in separate files.
4. Set Appropriate Degrees of Freedom
| Freedom Level | When to Use | Example |
|---|---|---|
| High (text instructions) | Multiple valid approaches | Code review guidelines |
| Medium (pseudocode/templates) | Preferred pattern with variation | Report generation |
| Low (specific scripts) | Fragile operations, consistency critical | Database migrations |
Common Patterns
Template Pattern
Provide output format templates for consistent results.
Examples Pattern
Show concrete input/output examples when output quality depends on seeing them.
Workflow Pattern
Break complex operations into clear steps with checklists.
Conditional Workflow Pattern
Guide through decision points with branching paths.
Feedback Loop Pattern
For quality-critical tasks, implement validation loops.
Skill Creation Workflow
Phase 1: Discovery
Gather purpose, location, trigger scenarios, requirements, existing patterns.
Phase 2: Design
Draft name, description, outline sections, identify supporting files.
Phase 3: Implementation
Create directory structure, write SKILL.md, create supporting files.
Phase 4: Verification
Verify under 500 lines, description is specific, consistent terminology, references one level deep.
Summary Checklist
- Description is specific and includes key terms (WHAT and WHEN)
- Written in third person
- SKILL.md body is under 500 lines
- Consistent terminology throughout
- Examples are concrete, not abstract
- File references are one level deep
- No time-sensitive information