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

1. Purpose and scope: What specific task or workflow should this skill help with?
2. Target location: Personal skill (~/.cursor/skills/) or project skill (.cursor/skills/)?
3. Trigger scenarios: When should the agent automatically apply this skill?
4. Key domain knowledge: What specialized information does the agent need?
5. Output format preferences: Are there specific templates or formats required?
6. 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

markdown
---
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

1. Write in third person: "Processes Excel files and generates reports"
2. Be specific and include trigger terms: Include both WHAT and WHEN
3. 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