cursor-create-skill

name	cursor-create-skill
description	Create Cursor Agent Skills. Guides through authoring a new skill including SKILL.md structure, directory layout, description best practices, common patterns (template, examples, workflow, conditional, feedback loop), and utility scripts. Use when authoring a new skill or asking about SKILL.md structure.
metadata	{"version":"0.1.0"}

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

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