Using agent-skills with Cursor

How to wire agent-skills into Cursor using current, supported project context — not legacy monolith files or Kaizen-specific layouts.

Every .cursor/ path in this guide lives in your project (or under ~/.cursor/ for user scope). This repository does not ship a .cursor/ directory: you create it and sync the skills into it, which is what step 1 does.

---

What Cursor supports today

Cursor combines rules (short policies) and skills (full workflows):

Layer	Path	Role
Project rules	.cursor/rules/*.mdc	Always-on or file-scoped instructions (alwaysApply, globs)
Project skills	.cursor/skills/<skill-name>/SKILL.md	Agent-discovered workflows; read when the task matches the skill description
User rules	Cursor Settings → Rules	Account-wide policies
User skills (optional)	~/.cursor/skills/	Global skills available in every workspace

Docs: Rules · Skills (URLs may redirect as Cursor updates docs).

Rules vs skills

• Rules — concise, stable (“use conventional commits”, “type-annotate public Python APIs”). Prefer one concern per file; avoid large pasted guides.
• Skills — step-by-step processes from this repo (test-driven-development, code-review-and-quality, etc.). Do not copy entire SKILL.md bodies into rules; that duplicates .cursor/skills/ and wastes context.

Legacy (avoid for new setups)

Legacy	Prefer
Root .cursorrules	.cursor/rules/*.mdc
Copying SKILL.md → .cursor/rules/	.cursor/skills/<name>/SKILL.md
“Load 10 skills as always-on rules”	1–2 thin alwaysApply rules + skills on demand

---

Recommended project layout

your-project/
├── .cursor/
│   ├── rules/                    # Short .mdc policies (yours)
│   │   └── agent-skills.mdc      # Optional: “use project skills” pointer
│   └── skills/                   # What Cursor Agent loads
│       ├── using-agent-skills/
│       ├── test-driven-development/
│       ├── code-review-and-quality/
│       └── …                     # Synced from agent-skills + your own skills
└── agent-skills/                 # Optional: git submodule or vendor clone
    └── skills/                   # Upstream source only

Source of truth for the agent: .cursor/skills/.
Treat agent-skills/skills/ (or a cloned addyosmani/agent-skills) as upstream — sync into .cursor/skills/, do not edit only upstream and expect Cursor to see it.

---

Setup (any repository)

1. Install skills into .cursor/skills/

From a local clone of agent-skills (at project root or elsewhere):

mkdir -p .cursor/skills
rsync -a /path/to/agent-skills/skills/ .cursor/skills/

First-time copy without overwriting your custom skills:

rsync -a --ignore-existing /path/to/agent-skills/skills/ .cursor/skills/

After upstream updates:

rsync -a /path/to/agent-skills/skills/ .cursor/skills/

Each skill folder must contain SKILL.md with YAML frontmatter, at minimum:

---
name: test-driven-development
description: Drives development with tests. Use when implementing logic, fixing bugs, or changing behavior.
---

Cursor uses description (and related metadata) to decide when to apply a skill.

2. Add minimal project rules (optional but useful)

Create .cursor/rules/agent-skills.mdc:

---
description: Use agent-skills workflows from .cursor/skills
alwaysApply: true
---

Before non-trivial technical work:

1. Route via `.cursor/skills/using-agent-skills/SKILL.md`.
2. Read and follow the matching skill under `.cursor/skills/<name>/SKILL.md`.
3. Open `reference.md` in that folder when the skill links to it.
4. Prefer project skills over guessing; user does not need to say "read skill" each time.

Add separate .mdc files for repo-specific standards (style, language, stack), keeping each file focused.

Rule file format:

---
description: Shown in Cursor rule UI
alwaysApply: false
globs: "**/*.{ts,tsx}"
---

# Your rule content

Field	Use
alwaysApply: true	Every chat in this project
globs	When matching files are in context
alwaysApply: false + no globs	Agent-request / manual rule (Cursor UI)

3. User-level skills (optional)

Copy or install skills you want everywhere under ~/.cursor/skills/. Use for stack-wide guides (e.g. language patterns) that are not part of agent-skills.

Project skills in .cursor/skills/ take precedence for this repo’s workflows.

4. Verify

1. Settings → Rules — project .mdc files listed.
2. Agent chat — skills from .cursor/skills/ appear in the skill list (if your Cursor build exposes it).
3. Run a task that maps to a skill (e.g. “add a feature with tests first”) without naming the file — agent should open test-driven-development when routing works.

---

How agents should use skills

1. Discover — using-agent-skills maps task phase → skill name.
2. Read — full process in .cursor/skills/<name>/SKILL.md.
3. Deep dive — reference.md, references/*.md, or linked checklists when the skill says so.
4. Combine — e.g. incremental-implementation + api-and-interface-design for an API slice.

Explicit user phrases (“follow TDD”, “use code-review-and-quality”) still help if the agent drifts.

Phase → skill (quick map)

You are…	Skill
Clarifying requirements	interview-me, idea-refine, spec-driven-development
Planning tasks	planning-and-task-breakdown
Implementing	incremental-implementation, frontend-ui-engineering, api-and-interface-design
Testing	test-driven-development, browser-testing-with-devtools
Debugging	debugging-and-error-recovery
Reviewing	code-review-and-quality, code-simplification
Security / performance	security-and-hardening, performance-optimization
Git / CI / ship	git-workflow-and-versioning, ci-cd-and-automation, shipping-and-launch

Full tree: skills/using-agent-skills/SKILL.md in the repo.

---

What not to do

Avoid	Do instead
Paste all skills into one rule	Sync to .cursor/skills/
Maintain two diverging copies	rsync from upstream; commit .cursor/skills/
Many alwaysApply: true rules	One routing rule + focused globs rules
Rely on .cursorrules only	Migrate to .mdc + skills
Expect agent-skills/agents/*.md to auto-load	Paste in chat, or distill a short rule

---

Context tips

• Keep always-on rules small (routing + 1–2 non-negotiables).
• Let skills carry long checklists and rationalization tables.
• Add phase-specific globs rules only when needed (e.g. **/*.py, **/components/**).
• Nudge by skill name if verification steps are skipped.

---

agents/ directory

Files under agent-skills/agents/ (e.g. code reviewer persona) are not loaded automatically by Cursor. Options:

• Reference the skill equivalent (code-review-and-quality).
• Paste agent markdown into the chat for one review.
• Extract a short checklist into a .mdc rule.

---

Troubleshooting

Symptom	Check
Skill never used	SKILL.md under .cursor/skills/<name>/? Valid frontmatter description?
Rules ignored	Extension .mdc? Correct alwaysApply / globs?
Stale workflow	Re-rsync from agent-skills/skills/
Duplicate instructions	Remove skill content from rules; keep one source
Wrong skill picked	Narrow description in custom skills; nudge in chat
"An unexpected error occurred on our servers" right after attaching a skill with /, and every later message in that chat fails too	Known Cursor-side issue, tracked in #494: Cursor pulls the attached SKILL.md into the request and the failure happens on its side, not in the skill. Start a new chat and reference the skill by name in plain text ("Use the test-driven-development skill to …") instead of attaching it.

---

Checklist (new project)

• mkdir -p .cursor/skills and sync from agent-skills/skills/
• Optional: .cursor/rules/agent-skills.mdc with routing hint
• Add repo-specific rules as separate small .mdc files
• Commit .cursor/skills/ and .cursor/rules/ (team shares behavior)
• Skip giant .cursorrules unless required by legacy tooling

---

See also

• getting-started.md
• ../README.md — Cursor quick blurb
• Upstream: github.com/addyosmani/agent-skills