Skill Authoring

Skills are selective-load information systems. Keep SKILL.md concise, route to detailed files, and verify outcomes with repeatable checks.

Mental Model

Startup:    Skill metadata (name/description) is pre-loaded
Trigger:    SKILL.md loads on demand
Navigation: Reference files load only when explicitly read
Execution:  Scripts can run without loading source into context

Design for discoverability first, then detail depth.

Visual Overview

flowchart TD
  metadata[metadata_name_description] --> hub[SKILL_md_hub]
  hub --> refs[reference_files_one_level]
  hub --> scripts[scripts_execute_or_read]
  hub --> evals[evaluations_and_model_tests]
  evals --> observe[observe_refine_test_loop]
  observe --> hub

Quick Reference

Storage Locations

Do not create skills in ~/.cursor/skills-cursor/.

Task Router

Creating a new skill? Start at Before You Begin, then follow Workflow.

Refreshing an existing skill? Start with Workflow step 1 and run evaluation-first updates before restructuring docs.

Skill is not triggering reliably? Use Description Requirements, then verify with checklist.md.

Need concrete templates? Use patterns.md for evals, runtime sections, validation loops, and output patterns.

Need failure examples to avoid? Use anti-patterns.md.

Before You Begin

Gather these requirements before writing or editing the skill:

1. Purpose: What exact task or workflow should this skill enable?
2. Knowledge gap: What does the agent need that it will not infer reliably?
3. Storage: Personal (~/.cursor/skills/) or project (.cursor/skills/)?
4. Triggers: When should this skill load?
5. Output format: Any template or strict structure required?

Use AskQuestion for structured collection when available.

Workflow

1) Discovery

Capture purpose, constraints, triggers, and output expectations from the user or conversation context.

2) Evaluation-First Setup

Before extensive docs:

1. Run representative tasks without the skill and record gaps.
2. Create at least three evaluation scenarios.
3. Define expected behaviors and pass conditions.
4. Decide which model tiers will be used and include them in test coverage.

Use templates in patterns.md.

3) Structure Design

skill-name/
├── SKILL.md          # Hub and routing (concise)
├── references/        # Optional detailed docs
│   └── *.md
└── scripts/          # Optional utility scripts
    └── *.py

Keep references one level deep from SKILL.md.

4) Authoring

Write SKILL.md as a navigation hub:

• Include frontmatter (name, description).
• Add TOC if file exceeds 100 lines.
• Keep common workflows inline and concise.
• Link to references with context.
• Add runtime/tooling guidance where relevant.

5) Verification

Run checks from checklist.md, including discovery quality, structure, runtime/tooling clarity, and validation patterns.

6) Observe-Refine-Test Loop

Use two instances conceptually:

• Authoring instance: updates instructions and structure.
• Testing instance: executes real tasks using the skill.

Observe behavior, capture misses, refine instructions, rerun evaluations, and repeat.

Description Requirements

Description is discovery-critical and must include:

1. Capabilities (what the skill does)
2. Triggers (when to use it)
3. Keywords (terms users are likely to say)
4. Third-person voice

# Good