How to write useful Cursor skills (not generic prompt dumps)

2026-11-09 · Translation: VI

A Cursor skill earns its place when it changes agent behavior on a recurring job: same constraints, same checkpoints, fewer corrective turns. A skill fails when it is a motivational essay, a copy of public docs, or a grab bag of “best practices” the model already knows. This note shows how to write skills that stay short, testable, and local to your work.

What a skill is for

Vague skills fail; specific skills survive real tasks.

Treat a skill as a procedure with constraints, not as a knowledge article. Good triggers:

• You correct the same mistake across chats (“don’t invent new folders,” “run these checks,” “use this ticket format”).
• A job has a fixed sequence (publish checklist, incident notes, schema migration).
• Domain rules are easy to violate and expensive to reverse.

Bad triggers:

• One-off questions
• Generic coding taste (“write clean code”)
• Entire product manuals pasted into Markdown

If the guidance is only useful once, put it in the prompt. If it is useful monthly, put it in a skill.

Anatomy that works

Working anatomy: trigger → constraints → steps → done checks.

Keep SKILL.md tight:

1. Frontmatter / title — name the job plainly (adsense-publish-check, write-guide).
2. When to use — two or three concrete trigger phrases.
3. Hard rules — numbered constraints the agent must not improvise around.
4. Steps — ordered actions with clear done criteria.
5. Inputs / outputs — files touched, artifacts produced.
6. Examples — one good and one bad invocation, not ten fictional stories.

Prefer imperatives: “Update content/queue/ideas.md every run.” Avoid soft filler: “Consider thoughtfully updating the queue when appropriate.”

Write constraints before inspiration

List failures you have already seen:

• Agent published without required frontmatter fields
• Agent expanded scope into unrelated folders
• Agent skipped the ranking criteria section
• Agent wrote hype or fake citations

Turn each failure into a rule. Rules beat vibes. Example:

Rankings must include updatedDate, an explicit criteria section, a markdown table, and a changelog. Refuse to publish if any are missing.

That sentence prevents an entire class of bad drafts.

Scope the filesystem

State which paths are in play and which are forbidden. Skills that say “improve the project” invite random refactors. Skills that say “only edit src/content/guides/{lang}/ and content/queue/ideas.md” stay reviewable.

If a skill may create files, specify naming, frontmatter schema, and word-count bands. If it must not commit or push, say so explicitly.

Make steps falsifiable

Each step should have an observable finish line:

• “Read content.config.ts and list required frontmatter keys.”
• “Draft 1100–1400 words; verify with a word count.”
• “Run through the AdSense publish checklist; fix failures before marking done.”

Avoid steps like “ensure quality” or “make it engaging.” Those are untestable, so agents invent theater.

Keep reusable prompts out of the skill body when possible

If you need a long template, link or store it as a sibling file the skill points to. The skill itself should remain the control plane: when to load the template, which fields are mandatory, what to validate after fill-in.

Test a skill like a flaky script

Test cycle: write → run → note failures → tighten.

Run the skill on a real task twice:

1. Fresh chat with only the skill trigger and minimal extra context.
2. A slightly messy request that tempts scope creep.

Pass criteria:

• Required files change; unrelated files do not
• Mandatory sections appear without you reminding
• The agent stops and asks when a required input is missing instead of fabricating

If you still need the same correction after two runs, the skill is incomplete—add a hard rule, not another paragraph of advice.

Anti-patterns to delete

• Generic persona blocks (“You are a world-class engineer…”) that do not change file-level behavior
• Duplicated repo README content the agent can read on demand
• Unbounded checklists with 40 items nobody runs
• Secret policy dumps that belong in private rules, not shared skills
• Overlapping skills that fight (two publish checkers with different rules)

Merge overlaps. One job, one skill.

Minimal example outline

# publish-guide

Use when drafting or finalizing a Forgebench guide.

## Hard rules
- Valid frontmatter per content.config.ts
- 1100–1400 words, practical, no hype, no fake citations
- Update content/queue/ideas.md every run

## Steps
1. Confirm topic and translationKey
2. Draft against the outline
3. Self-check against adsense-publish-check
4. Update the ideas queue with status

## Done when
- Guide file exists with draft: false only if checklist passed
- Queue entry updated

Ship skills that remove repeated supervision. If a skill does not reduce your correction rate within a week, rewrite the rules—or delete it.