Agent Skill for Cursor: How Skills and Rules Fit Together

An agent skill for Cursor is a reusable workflow package that teaches Cursor Agent how to perform a specific job: review a pull request, debug a failing build, migrate a component API, test a route in the browser, write release notes, or follow a team-specific incident runbook.

Cursor now documents Agent Skills as an open standard for packaging specialized knowledge, scripts, templates, and references. Cursor discovers skills from project and user directories such as .agents/skills/, .cursor/skills/, ~/.agents/skills/, and ~/.cursor/skills/. It can surface a skill automatically when the task matches the skill description, or you can invoke one manually from Agent chat with /skill-name.

That makes skills a first-class companion to Cursor rules, not a replacement for them. Rules provide persistent context. Skills provide task procedures. If you are still defining the basic concept, start with What Is an Agent Skill?.

Cursor rules are for instructions that should shape many interactions. Cursor supports project rules in .cursor/rules, user rules in your local environment, team rules from the dashboard, and AGENTS.md files as a simpler Markdown instruction format. Project rules use .mdc files with frontmatter that controls when the rule is included: always, by file pattern, by agent relevance, or only when manually mentioned.

Skills are more like named runbooks. A skill is a folder with a SKILL.md file and optional scripts/, references/, and assets/ folders. The frontmatter names the skill, describes when to use it, and can scope it to paths. Cursor's skills docs also support disable-model-invocation: true when a skill should behave like an explicit slash command instead of being selected automatically.

The short version:

Put it in	When it should apply	Good example
Cursor user rule	Personal preference across projects	"Answer concisely and ask before destructive commands."
Cursor project rule	Repo convention across many tasks	"Use Zod at API boundaries and run npm test before handoff."
Cursor team rule	Organization standard	"Never expose customer secrets in logs or screenshots."
AGENTS.md	Simple readable project instructions	"Read docs before editing and preserve user changes."
Agent skill	One repeatable workflow	"Reproduce a reported bug, add a failing test, patch it, and return evidence."

For the broader distinction, Agent Skill vs Rules makes the same point outside Cursor: rules are persistent constraints; skills are reusable procedures.

Use a Cursor rule when the instruction should be true even if nobody mentions a special workflow. Use a skill when the instruction belongs to a job that starts, runs, and ends.

A project rule might say:

Use `npm test` for the full test suite.
Use `npm run lint` before submitting UI changes.
Follow the existing App Router patterns.

A migration skill would go further:

---
name: next-route-migration
description: Migrate one legacy route to the App Router. Use when a specific route is assigned. Do not use for broad architecture redesigns.
---

Read the current route, tests, route-level docs, and examples first.
Write or update a failing route test before moving code.
Move only the assigned route and preserve existing user edits.
Run the focused test, lint, and build.
Report changed files, commands, screenshots if relevant, and remaining risk.

The rule gives background constraints. The skill gives the sequence of work, the stop conditions, and the evidence another engineer can inspect.

This is also where Agent Skill vs Code matters. The skill should not ask Cursor to mentally validate every case. If the workflow has a deterministic step, put it in a script or test and have the skill run it. A bug-reproduction-and-fix skill can require the agent to run npm test -- bug-name.test.ts; the test is the proof.

A small project skill can live in .cursor/skills/ if it is Cursor-specific, or .agents/skills/ if you want the same package to be available to other skills-compatible agents. Cursor's docs say it loads both locations, plus user-level equivalents. For a team repo, .agents/skills/ is often the cleaner default because it signals that the workflow is portable.

.agents/
  skills/
    bug-reproduction-and-fix/
      SKILL.md
      scripts/
        collect-test-evidence.sh
      references/
        testing-conventions.md

The SKILL.md file should be short enough for the agent to use directly. Put long checklists, example reports, migration matrices, or troubleshooting notes in references/. Cursor and the open Agent Skills standard both lean on progressive disclosure: the agent starts with the skill name and description, loads the full instructions only when relevant, and loads deeper resources only when the workflow calls for them.

For monorepos, Cursor can also discover nested skills. A repo-wide skill might live at .agents/skills/release-review/SKILL.md, while an app-specific deployment skill might live under apps/web/.agents/skills/deploy-web/SKILL.md.

The strongest Cursor skills are concrete enough that another developer can tell whether the workflow finished. They define a trigger, required inputs, trusted source order, edit boundary, verification commands, stop rules, and output shape. Here is a complete example for code review:

---
name: pr-risk-review
description: Review a pull request diff for correctness, regression risk, missing tests, and unsafe scope. Use when asked to review a PR, branch, or staged diff.
paths:
  - "**/*.ts"
  - "**/*.tsx"
  - "**/*.md"
---

## Workflow

1. Read the diff against the target branch.
2. Read project rules and any nested AGENTS.md files that apply to changed files.
3. Identify behavior changes before style comments.
4. Check tests around modified modules.
5. Run the smallest useful verification command when available.
6. Return findings first, ordered by severity, with file paths and evidence.

## Stop rules

Stop and ask before reviewing generated files, secrets, vendor code, or a diff that mixes unrelated product areas.

This is not just "review carefully." It names the trigger, file scope, sequence, evidence standard, and stop conditions.

The trigger is especially important. OpenAI's Codex skills documentation emphasizes that agents decide whether to load a skill from its description before reading the full SKILL.md. Cursor's skill format follows the same pattern. A vague description like "helps with frontend work" competes with every other frontend instruction. A description like "Use when migrating one React component from legacy props to the v2 design-system API" gives the agent a real selection boundary.

GitHub's Copilot docs describe the same split: custom instructions are for simple guidance relevant to almost every task, while agent skills are for detailed instructions Copilot should access only when relevant. VS Code's Agent Skills documentation is even more explicit: skills can include instructions, scripts, examples, and resources, while custom instructions mainly define coding standards.

Suppose your repo is migrating a design system from ButtonLegacy to Button. A Cursor rule can carry stable conventions:

When editing React components, use named exports.
Do not add raw color values; use design tokens from `src/styles/tokens.ts`.
Follow examples in `src/components/forms/TextField.tsx`.

Those rules should apply across many frontend tasks. They do not explain how to run the migration.

A component-api-migration skill can define the job:

• Inspect docs/design-system/button-v2.md.
• Find usages of ButtonLegacy only in the assigned package.
• Update one component family at a time.
• Replace variant="primary" with tone="accent" only where the migration table says so.
• Run npm test -- Button and npm run lint -- --file <changed-file> if the repo supports focused linting.
• Return a before/after prop summary and any skipped cases.

The rule keeps Cursor aligned with the repo's normal frontend style. The skill prevents the agent from turning a one-component migration into a broad redesign.

Cursor Agent can use browser tools for testing applications, auditing accessibility, and visually inspecting layouts. That does not mean every UI instruction belongs in a rule.

A durable rule might say:

For UI changes, check desktop and mobile behavior before final handoff when practical.

A frontend-qa skill should be more procedural:

Use when a route, component, or visual state changed.

1. Start the local dev server using the package manager already used by the repo.
2. Open the changed route.
3. Capture desktop and mobile evidence.
4. Check loading, empty, error, and populated states when fixtures exist.
5. Verify text does not overlap and interactive controls are reachable by keyboard.
6. Report exact route, viewport sizes, browser issues, and files changed.

If this workflow becomes frequent, the skill can call a Playwright script or screenshot helper. The skill decides when and why to run the check; the script handles deterministic browser steps.

Some instructions are too foundational to hide inside a skill. Keep them in rules or AGENTS.md when violating them would be wrong in almost every task:

• never overwrite user changes
• use npm commands for dependency updates
• do not edit generated files
• follow repository-specific auth and database boundaries
• prefer established project patterns over new libraries
• ask before destructive filesystem or production actions

Cursor's rules docs recommend focused, actionable, scoped rules and warn against copying entire style guides or documenting every common command. A useful rule points to canonical files instead of pasting stale examples. A rule like "follow src/api/errors.ts for API error shape" usually beats a 200-line explanation of every error case.

Community discussions around Cursor rules tend to land on the same practical advice: keep always-on rules small, use file-scoped rules for framework patterns, and use descriptions for agent-selected guidance. In one Cursor rules discussion on Reddit, users argued that rules should describe how to build, not what feature to build, and that real file paths beat generic advice. That is also a good test for whether a rule should become a skill. If the instruction reads like "do this job from start to finish," extract it.

Good Cursor skill candidates are repeatable, bounded, and evidence-producing:

• bug-reproduction-and-fix: reproduce a bug, add a failing test, patch, verify.
• component-api-migration: update one component family to a new prop API.
• release-note-from-diff: turn merged changes into user-facing release notes.
• frontend-qa: run a browser QA pass against changed routes.
• github-actions-failure-debugging: inspect failed logs, identify the failing job, patch the smallest cause, and rerun focused checks.
• docs-from-code-change: update user-facing docs only for behavior that actually changed.

Weak candidates:

• "be a better developer"
• "write all code well"
• "improve this repo"
• "always make beautiful UI"
• "understand our architecture"

Those are too broad to trigger reliably. They belong in conventions, training, or smaller skills. If you want a reusable skill that survives real work, How to Write an Agent Skill That Actually Works covers the authoring pattern in more detail.

Overloaded rule files usually start with coding standards, then accumulate one-off workflows: how to review a pull request, prepare a release, write migration notes, test the billing flow, or create a new dashboard widget.

The refactor is mechanical:

1. Keep always-true constraints in rules.
2. Move named workflows into .agents/skills/<skill-name>/SKILL.md or .cursor/skills/<skill-name>/SKILL.md.
3. Put long examples in references/.
4. Turn repeated shell commands into scripts when they need exactness.
5. Test each skill with an explicit /skill-name invocation before trusting automatic selection.

Cursor also documents a built-in /migrate-to-skills skill that can convert eligible dynamic rules and slash commands into skills. That is useful for cleanup, but review the result manually. Migration can preserve structure; it cannot decide whether your trigger is too vague or whether a script should replace a paragraph of instructions.

Skills make Cursor more consistent, but they are not magic. The first tradeoff is invocation. Automatic selection depends on the task, context, and description field. In a Cursor forum thread about using Agent Skills, one user noted that automatic selection may be unreliable enough that manual invocation is sometimes better. That matches the broader pattern in skills-compatible tools: make descriptions specific, but give critical workflows an easy slash-command path.

The second tradeoff is maintenance. A stale skill can be worse than no skill because it gives the agent a confident but outdated procedure. Point to canonical files and prune instructions when the repo changes. If the skill depends on a script, treat that script like product code.

The third tradeoff is portability. .cursor/skills/ is obvious to Cursor users, while .agents/skills/ is better if the same workflow should work in Cursor, VS Code Copilot, Codex, or other agents that follow the open standard. VS Code supports project skills in .github/skills/, .claude/skills/, and .agents/skills/; GitHub's Copilot docs describe skills in .github/skills, .claude/skills, or .agents/skills for repository-specific use. If your team is multi-tool, choose the location that reduces duplication.

The fourth tradeoff is safety. Skills can include scripts, and Cursor docs say agents may run referenced scripts when the skill is invoked. Third-party skills deserve the same review you would give a shell script from a dependency. Read the SKILL.md, inspect scripts, and prefer pinned internal copies for sensitive workflows.

Before you add a Cursor skill, check the contract:

• Is the workflow narrower than the repo's general rules?
• Does the description say exactly when to use it?
• Does it say which files, docs, or examples to inspect first?
• Does it preserve existing user edits?
• Does it define an edit boundary?
• Does it require verification, not just code generation?
• Does it stop before broad refactors or missing credentials?
• Does it report evidence another engineer can inspect?
• Does it belong in .agents/skills/ for portability or .cursor/skills/ for Cursor-only use?

For quality control, How to Test an Agent Skill Before You Publish It is the companion step. A skill is only reusable if it can survive realistic prompts, missing context, dirty worktrees, and a developer who expects proof.

Use Cursor rules for persistent context. Use agent skills for repeatable work.

When teams confuse the two, rules become bloated and skills become generic. Keep rules short enough to guide every task. Put named procedures in skills with triggers, sources, boundaries, verification, and output evidence.

That pairing is the useful Cursor setup: rules keep the agent inside the repo's operating environment, while skills tell it how to complete a specific recurring job without dragging every workflow into every prompt.