Login

How to Define Cursor Skills (Rules vs Skills + Code Review Example)

Learn how to define Cursor Agent Skills, why they beat ad-hoc prompts, how they differ from rules, and how to pair both. Includes a concrete /run-code-review skill for a PHP WordPress SEO plugin.

Lucas PHP/WordPress Developer 12 min read 29

Rules tell Cursor what must always be true. Skills tell Cursor how to run a specific job when you ask for it. If you keep pasting the same multi-step prompt for deploy, review, or release, that workflow belongs in a skill.

This guide covers what Agent Skills are, why they beat ad-hoc prompts, how they differ from rules, how to pair both, and a concrete /run-code-review skill for a PHP / WordPress SEO plugin. Details match Cursor’s skills docs as of October 2026.

What skills are for

A skill is a portable package: a folder with a SKILL.md file (and optional scripts, references, or assets) that teaches Agent a domain-specific workflow. Cursor discovers skills at startup. You can invoke one with /skill-name, or let Agent apply it when the description matches the request.

Skills shine when the task is repeatable and longer than a few bullets: code review checklists, staging deploys, migration playbooks, SEO audits. They are version-controlled, shareable through the repo, and progressive—Agent loads the main instructions first and pulls references only when needed.

  • Turn a long prompt into a named command the whole team can run.
  • Encode steps the model will not invent the same way twice.
  • Keep heavy procedure out of always-on rules so everyday chats stay lean.
  • Attach scripts and checklists next to the instructions that use them.

Why skills are useful

Without skills, every review or release starts from scratch. Someone remembers half the checklist. Someone else forgets escaping or schema markup. A skill makes the process explicit and callable.

  • Consistency — The same review order, the same output sections, every time.
  • Context efficiency — Detailed steps load when you run the skill, not on every chat.
  • Team handoff — Junior and senior developers invoke the same /run-code-review.
  • Composability — Pair a short Always Apply rule with a long skill instead of stuffing both into one giant rule file.

“Rules are the seatbelt. Skills are the checklist you run before the flight.”

Rules vs skills

Cursor’s own help page draws a clean line. Use it when you wonder which file to create.

RulesSkills
PurposeShort coding guidelines and constraintsMulti-step workflows and procedures
LengthA few lines to a few hundred linesOften longer, with step-by-step instructions
How appliedIncluded when Always Apply, globs, or intelligent match firesInvoked with /skill-name or applied when the description fits
Typical home.cursor/rules/*.mdc.cursor/skills/skill-name/SKILL.md
Example“Escape all output with WordPress APIs”“Run SEO plugin code review: security, escaping, schema, then report”

Rule of thumb: if the instruction must hold in almost every chat, make a rule. If you only need it when someone asks for that job, make a skill.

Pair skills with Cursor rules

Skills and rules are not competitors. The strongest setup uses both:

  • Rules hold invariants: escaping, no Cursor co-author trailers, brand button variants, “ask before editing wp-config.php.”
  • Skills hold procedures: how to review a PR, how to ship a release, how to audit SEO output.

For a WordPress SEO plugin, a glob rule on **/*.php can say “use esc_html(), nonces, and capability checks.” The /run-code-review skill then walks Agent through reading the diff, checking schema and meta tags, and writing a structured report. The rule keeps everyday edits safe. The skill makes the full review repeatable.

Practical advice:

  • Do not copy your entire PHP style guide into the skill. Reference the rule and focus the skill on the workflow.
  • Keep Always Apply rules short so they do not crowd out the skill’s steps.
  • If a dynamic rule is really a procedure, migrate it with /migrate-to-skills (Cursor 2.4+) instead of leaving a long intelligent rule that rarely fires cleanly.
  • Test the pair: start a chat, confirm the rule is active, then run /run-code-review and check that both hygiene and checklist show up in the result.

Where to place Cursor skills

Project skills: .cursor/skills/

Default for a real codebase. Commit the folder so teammates get the same /skill-name. Cursor also loads .agents/skills/, and nested trees such as apps/web/.cursor/skills/ in a monorepo (those nested skills are scoped to that directory).

Personal skills: ~/.cursor/skills/

Global on your machine. Good for personal workflows. They do not land in Cloud Agents until you turn on Sync Skills under Settings → Agents. To share with the team, put the skill in the repo or publish it to your team marketplace—do not rely on personal sync for shared process.

Compatibility paths

Cursor also discovers skills under Claude and Codex directories (.claude/skills/, .codex/skills/, and the user-level equivalents). Prefer .cursor/skills/ for new Cursor work so the layout matches the rest of the project.

File tree guide

Each skill is a directory whose name matches the name in frontmatter. Keep related skills under category folders if you want; Cursor walks the skills root recursively and treats the folder that contains SKILL.md as the skill identity.

your-seo-plugin/
├── AGENTS.md
├── .cursor/
│   ├── rules/
│   │   ├── no-cursor-coauthor.mdc      # Always Apply
│   │   └── wordpress-php.mdc           # Globs: **/*.php
│   └── skills/
│       └── run-code-review/
│           ├── SKILL.md                # Required
│           ├── references/
│           │   └── seo-checklist.md    # Optional, loaded on demand
│           └── scripts/                # Optional helpers
├── includes/
├── admin/
└── readme.txt

What belongs where:

  • .cursor/rules/*.mdc — Short constraints that should apply without typing a slash command.
  • .cursor/skills/*/SKILL.md — Named workflows you invoke when needed.
  • references/ — Long checklists Agent can open only during that skill run.
  • scripts/ — Optional validators the skill tells Agent to run.

How to structure a SKILL.md

Every skill needs YAML frontmatter and a markdown body. Required fields are name and description. Optional fields include paths (scope to file globs) and disable-model-invocation (only run when you type /skill-name).

FieldRequiredRole
nameYesLowercase, hyphens; must match the folder name
descriptionYesWhat it does and when to use it (discovery + auto-apply)
pathsNoOnly surface the skill when matching files are in play
disable-model-invocationNoWhen true, explicit / only—no auto apply

Skeleton:

---
name: run-code-review
description: Review PHP and WordPress SEO plugin changes for security, escaping, performance, and SEO output. Use when the user asks for a code review, PR review, or /run-code-review.
disable-model-invocation: true
---

# Run code review

## Instructions
1. …
2. …

## Output format
…

Writing tips that keep skills useful

  • Write the description in third person, with both WHAT and WHEN, and trigger phrases like “code review” or “SEO plugin.”
  • Keep SKILL.md concise. Move long matrices into references/.
  • Assume the agent is already smart. Add only project-specific steps and standards.
  • Set disable-model-invocation: true for expensive reviews so they only run when you type /run-code-review.
  • Use paths when the skill only makes sense for PHP (or admin UI) files.

How to add a skill

  1. Decide project vs personal: team workflow → .cursor/skills/ in the repo.
  2. In Agent, run /create-skill and describe the workflow, or create the folder and SKILL.md by hand.
  3. Set name to match the folder. Write a sharp description.
  4. Add steps, output format, and optional references/ or scripts/.
  5. Commit the skill. Confirm it appears under Customize → Skills.
  6. Test it: open Agent chat, type /run-code-review, point at a PR or diff, and check the report shape.

Concrete example: /run-code-review for a WordPress SEO plugin

Imagine a PHP plugin that writes titles, meta descriptions, canonicals, sitemaps, and JSON-LD. A vague “please review this” prompt produces uneven results. A skill forces the same pass every time: security and WordPress APIs first, then SEO-specific output, then a fixed report.

Create .cursor/skills/run-code-review/SKILL.md:

---
name: run-code-review
description: >-
  Review PHP and WordPress SEO plugin diffs for security, escaping, capabilities,
  performance, and SEO output (titles, meta, canonical, sitemap, schema).
  Use when the user asks for a code review, PR review, or runs /run-code-review.
disable-model-invocation: true
paths:
  - "**/*.php"
  - "assets/**/*.{js,css}"
---

# Run code review (WordPress SEO plugin)

## Before you start

1. Identify the change set: git diff, PR, or files the user named.
2. Read applicable project rules (WordPress PHP, commit hygiene). Do not restate them; enforce them.
3. If scope is unclear, ask once: full plugin audit or only the current diff?

## Review order

Work in this order. Skip a section only when it cannot apply.

1. **Security and WordPress APIs**
   - Nonces and capability checks on every admin or AJAX action.
   - Sanitize input (`sanitize_text_field`, `absint`, allowlists). Escape output (`esc_html`, `esc_attr`, `esc_url`, `wp_kses_post`).
   - No direct SQL without `$wpdb->prepare`. No secrets in the repo or web-accessible paths.
   - Hooks and load order: do not bootstrap heavy SEO logic on unrelated front-end requests without a need.

2. **SEO behavior**
   - Title and meta description: length sanity, no duplicate filters stacking blindly.
   - Canonical and robots: no accidental `noindex` on public posts; pagination and archives handled on purpose.
   - Sitemap: valid URLs, excluded post types respected, no admin-only URLs.
   - Schema / JSON-LD: valid JSON, no broken `@type`, no leaking private content.
   - Conflicts: detect obvious clashes with common SEO plugins only when the diff touches output hooks.

3. **Performance and maintainability**
   - Avoid N+1 queries in sitemap or meta generation.
   - Autoload options: do not autoload large SEO blobs.
   - Naming, file placement, and i18n (`esc_html__`, text domain) match the plugin.

4. **Tests and docs**
   - Note missing tests for new output filters or REST routes.
   - Flag readme / changelog gaps only when the change is user-facing.

## Output format

Use exactly these sections:

### Summary
One short paragraph: safe to ship / needs changes / blocked.

### Findings
Ordered by severity: Blocker, Major, Minor, Nit.
For each finding: file path, what is wrong, why it matters for SEO or security, and a concrete fix direction.
Do not invent issues. If the diff is clean in a section, say so in one line.

### What looks good
Two to five bullets on solid patterns in the change.

### Suggested next steps
Checklist the author can run (tests to add, WP-CLI checks, staging verify).

## Rules of engagement

- Prefer evidence from the diff over generic WordPress lectures.
- Do not expand scope into refactors the user did not ask for.
- Do not run destructive git or WP-CLI commands.
- If both a fix and an exploit-style PoC are requested, provide the fix only.

Optional reference file

Keep the long SEO matrix out of the main skill so everyday context stays small. Add .cursor/skills/run-code-review/references/seo-checklist.md with title length ranges, schema types you support, and sitemap exclusion rules. In SKILL.md, tell Agent: “Open references/seo-checklist.md when reviewing meta or schema changes.”

Pair it with a PHP rule

Alongside the skill, keep a short glob rule so normal edits stay clean even when nobody runs a review:

---
description: WordPress PHP standards for this SEO plugin
globs: "**/*.php"
alwaysApply: false
---

# WordPress PHP

- Escape all output. Sanitize all input. Use nonces and current_user_can on mutating requests.
- Prefer WordPress APIs over raw SQL or custom HTTP stacks.
- Do not edit wp-config.php, .htaccess, or production credentials unless the user names the file and confirms.
- Keep SEO output filters removable: use named functions or classes, not opaque closures when the plugin must unhook them.

Why this shape works

  • disable-model-invocation: true — Full reviews are expensive; you opt in with /run-code-review.
  • paths — The skill surfaces for PHP and front-end assets, not for unrelated markdown chores.
  • Fixed review order — Security before SEO vanity, so Agent does not skip nonces to discuss title length.
  • Fixed output — Summary → Findings → What looks good → Next steps. Easy to paste into a PR.
  • Rule + skill — Everyday PHP hygiene stays in the rule; the checklist lives in the skill.

How to verify it

  1. Commit .cursor/skills/run-code-review/ and the PHP rule.
  2. Open a fresh Agent chat in the plugin repo.
  3. Type /run-code-review and point at a branch, PR, or staged diff that touches meta or schema output.
  4. Confirm the reply uses the four report sections and cites real file paths.
  5. Confirm a normal “add a settings field” chat does not auto-run the full review (because model invocation is disabled).

A small set to start with

You do not need a skill catalog on day one. For most WordPress product repos, three pieces are enough:

  • Always Apply rule — Commit / PR hygiene (no Cursor co-author trailers).
  • Glob rule — WordPress PHP (or SCSS) constraints.
  • One skill — /run-code-review (or deploy / release) for the workflow you repeat weekly.

Add another skill only when you catch yourself pasting the same multi-step prompt again. Prefer one sharp skill over five vague ones.

Questions developers ask

Will Agent run my skill without asking?

By default, Agent may apply a skill when the description matches. Set disable-model-invocation: true if the skill should behave like a classic slash command and only run when you type /skill-name.

Should this be a rule or a skill?

If it is a short constraint that must hold often, use a rule. If it is a multi-step procedure you run on demand, use a skill. When in doubt, put the invariant in a rule and the checklist in a skill, then pair them.

Can I migrate old commands or dynamic rules?

Yes. Run /migrate-to-skills in Agent (Cursor 2.4+). It converts eligible “Apply Intelligently” rules and slash commands into skills. Always Apply and glob-scoped rules stay as rules—that split is intentional.

Final words

Define skills as named folders under .cursor/skills/, give each a clear description, and keep the heavy steps out of Always Apply rules. Pair a short WordPress PHP rule with a /run-code-review skill so everyday edits stay safe and full reviews stay consistent.

Start with the SEO plugin review skill above, invoke it on the next PR that touches titles or schema, and tighten the checklist only where Agent misses something twice. Same structure as rules: small files, one job, easy to test.