Agent Skills

Agent Skills are version-controlled instruction packs that teach an agent a repeatable workflow — PR review, release notes, migration checklists — without re-prompting every session.

The problem

Project rules (AGENTS.md, .cursor/rules/) answer "how does this repo work?" Skills answer "how do I run this workflow?" — a security review, a deploy checklist, a Markdoc page from the growth playbook.

Without skills, teams paste the same multi-paragraph prompt into every session. With skills, the agent loads instructions on demand and follows a tested procedure.

Skills vs rules vs MCP

Rules stay lean. Skills hold procedural depth. MCP handles runtime access skills cannot provide.

See Project Rules for rules authoring and Building MCP Servers when a skill needs live data.

Directory layout

Each skill is a folder with a required SKILL.md:

my-skill/
├── SKILL.md           # Required — frontmatter + instructions
├── references/        # Optional — loaded on demand
│   └── standards.md
├── scripts/           # Optional — executable helpers
│   └── validate.sh
└── assets/            # Optional — templates, config samples

Where skills live

Do not author skills under ~/.cursor/skills-cursor/ — that directory is reserved for Cursor built-in skills.

The folder name must match the name field in frontmatter (lowercase letters, numbers, hyphens; max 64 chars).

SKILL.md structure

Every skill starts with YAML frontmatter, then markdown instructions:

---
name: security-review
description: >-
  Review diffs for SQL injection, hardcoded secrets, missing auth checks,
  and XSS. Use when reviewing pull requests, examining staged changes,
  or when the user asks for a security review.
disable-model-invocation: true
paths: src/**/*.ts, src/**/*.tsx
---

# Security Review

## Checklist

- [ ] Parameterized queries only — no string-concatenated SQL
- [ ] No secrets in source; env vars server-side only
- [ ] Mutations call auth middleware before business logic
- [ ] No dangerouslySetInnerHTML without sanitization

## Output format

Return pass/fail per category with severity (critical / warning / info).

Frontmatter fields

Description quality matters. Vague descriptions never trigger. Good: "Generate commit messages from staged diffs following Conventional Commits. Use when the user asks for a commit message or reviews staged changes." Bad: "Helps with git."

Default disable-model-invocation: true for destructive or expensive workflows (deploys, migrations). Omit it when you want ambient discovery (e.g. a Markdoc authoring skill scoped with paths).

Progressive disclosure

Keep SKILL.md under ~500 lines. Put reference material in sibling files the agent reads only when needed:

## Additional resources

- Full coding standards: [references/standards.md](references/standards.md)
- Example reviews: [references/examples.md](references/examples.md)

Link one level deep from SKILL.md — nested reference chains lead to partial reads.

Scripts in skills

Reference executable helpers with paths relative to the skill root. In the skill body, tell the agent to run the script — do not nest code fences inside a SKILL.md example:

## Validate before merge

Run: bash scripts/validate-markdoc.sh <file>

Do not reimplement the checker inline. Fix reported errors before finishing the task.

Scripts beat generated one-offs when the operation is fragile or must be identical every time.

Invocation

Test discovery by starting a fresh session and asking for the workflow without naming the skill. If it does not load, tighten the description trigger terms or remove disable-model-invocation.

Example: content page skill

Project skill for this site's Markdoc pages:

.cursor/skills/add-markdoc-page/
├── SKILL.md
└── references/
    └── checklist.md

---
name: add-markdoc-page
description: >-
  Add a Markdoc content page to a Next.js Pages Router site — frontmatter,
  navigation.js registration, cross-links. Use when creating pages under
  src/pages/ or when the user mentions Markdoc, navigation.js, or content growth.
paths: src/pages/**/*.md
---

# Add Markdoc Page

1. Create `src/pages/<path>.md` with required frontmatter: title, pageTitle, description, date (MM-DD-YYYY).
2. First paragraph ends with the Markdoc lead annotation; add a Last reviewed callout.
3. Register in `src/shared/navigation.js` — href without trailing slash.
4. Cross-link from one related existing page.
5. Run `npm run dev` and open the new URL with trailing slash.

Allowed Markdoc tags only — see `markdoc/tags.js`. No MDX or JSX.

Production concerns

Team rollout

Skills complement Agentic Workflows — the skill is the playbook; the agent loop executes it.

Related

• Project Rules and AGENTS.md — persistent repo conventions
• Building MCP Servers — when skills need live tool access
• Agentic Workflows — plan → implement → review loops
• Claude Code — skills, hooks, and terminal agent patterns
• Context Engineering — token budgeting across rules and skills