Writing Skills for Cursor

Adapted from obra/superpowers for Cursor IDE.

Overview

Skills are portable, version-controlled packages that teach agents how to perform domain-specific tasks. In Cursor, skills live in ~/.cursor/skills/<skill-name>/SKILL.md (user-level) or .cursor/skills/<skill-name>/SKILL.md (project-level).

Skill Structure

~/.cursor/skills/
  skill-name/
    SKILL.md          # Main reference (required)
    scripts/           # Optional executable scripts
    references/        # Optional additional docs
    assets/            # Optional templates, configs

SKILL.md Format

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions and symptoms]
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
Bullet list with symptoms and use cases.

## Core Pattern
Before/after code comparison or key steps.

## Quick Reference
Table or bullets for scanning.

## Common Mistakes
What goes wrong + fixes.

Key Rules

1. •Name: Lowercase letters, numbers, hyphens only. Must match folder name.
2. •Description: Start with "Use when..." — describe triggering conditions ONLY, never summarize the workflow (agent may follow description instead of reading full skill).
3. •Keep focused: One skill = one responsibility. Under 500 words for frequently-loaded skills.
4. •Real examples: One excellent example beats many mediocre ones.
5. •Cross-reference: Use skill names, not file paths. Mark required skills explicitly.

Description Anti-Patterns

# BAD: Summarizes workflow
description: Use for TDD - write test first, watch it fail, write minimal code

# GOOD: Just triggering conditions
description: Use when implementing any feature or bugfix, before writing implementation code

Testing Skills

Before deploying a new skill:

1. •Test without the skill (baseline behavior)
2. •Test with the skill (should improve)
3. •Find rationalizations agents use to skip it
4. •Add explicit counters in the skill
5. •Re-test until bulletproof