Skip to content

cursor-setup.md

Latest commit

 

History

History
225 lines (158 loc) · 8.17 KB

cursor-setup.md

File metadata and controls

225 lines (158 loc) · 8.17 KB
Raw

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.

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

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