From d05b2522c9e68a0c0629a676ad353be803292a03 Mon Sep 17 00:00:00 2001 From: Nguyen Duc Thao Nguyen Date: Fri, 5 Jun 2026 09:44:23 +0700 Subject: [PATCH] docs: update Cursor setup guide for rules and skills layout Reflect current Cursor project context (.cursor/rules + .cursor/skills) instead of legacy monolith patterns. --- README.md | 2 +- docs/cursor-setup.md | 237 ++++++++++++++++++++++++++++++++++++------- 2 files changed, 203 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index ad6afcf..fbc67fb 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ claude --plugin-dir /path/to/agent-skills
Cursor -Copy any `SKILL.md` into `.cursor/rules/`, or reference the full `skills/` directory. See [docs/cursor-setup.md](docs/cursor-setup.md). +Put workflow skills under `.cursor/skills/` (sync from `agent-skills/skills/`) and short policies in `.cursor/rules/*.mdc` — do not paste full skills into rules. See [docs/cursor-setup.md](docs/cursor-setup.md).
diff --git a/docs/cursor-setup.md b/docs/cursor-setup.md index 11ac905..5fdde51 100644 --- a/docs/cursor-setup.md +++ b/docs/cursor-setup.md @@ -1,58 +1,225 @@ # Using agent-skills with Cursor -## Setup +How to wire [agent-skills](../README.md) into **Cursor** using current, supported project context — not legacy monolith files or Kaizen-specific layouts. -### Option 1: Rules Directory (Recommended) +--- -Cursor supports a `.cursor/rules/` directory for project-specific rules: +## What Cursor supports today -```bash -# Create the rules directory -mkdir -p .cursor/rules +Cursor combines **rules** (short policies) and **skills** (full workflows): -# Copy skills you want as rules -cp /path/to/agent-skills/skills/test-driven-development/SKILL.md .cursor/rules/test-driven-development.md -cp /path/to/agent-skills/skills/code-review-and-quality/SKILL.md .cursor/rules/code-review-and-quality.md -cp /path/to/agent-skills/skills/incremental-implementation/SKILL.md .cursor/rules/incremental-implementation.md +| Layer | Path | Role | +|-------|------|------| +| **Project rules** | `.cursor/rules/*.mdc` | Always-on or file-scoped instructions (`alwaysApply`, `globs`) | +| **Project skills** | `.cursor/skills//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](https://docs.cursor.com/context/rules) · [Skills](https://docs.cursor.com/context/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//SKILL.md` | +| “Load 10 skills as always-on rules” | 1–2 thin `alwaysApply` rules + skills on demand | + +--- + +## Recommended project layout + +```text +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 ``` -Rules in this directory are automatically loaded into Cursor's context. +**Source of truth for the agent:** `.cursor/skills/`. +Treat `agent-skills/skills/` (or a cloned [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)) as **upstream** — sync into `.cursor/skills/`, do not edit only upstream and expect Cursor to see it. -### Option 2: .cursorrules File +--- -Create a `.cursorrules` file in your project root with the essential skills inlined: +## Setup (any repository) + +### 1. Install skills into `.cursor/skills/` + +**From a local clone of agent-skills** (at project root or elsewhere): ```bash -# Generate a combined rules file -cat /path/to/agent-skills/skills/test-driven-development/SKILL.md > .cursorrules -echo "\n---\n" >> .cursorrules -cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> .cursorrules +mkdir -p .cursor/skills +rsync -a /path/to/agent-skills/skills/ .cursor/skills/ ``` -## Recommended Configuration +**First-time copy without overwriting your custom skills:** -### Essential Skills (Always Load) +```bash +rsync -a --ignore-existing /path/to/agent-skills/skills/ .cursor/skills/ +``` -Add these to `.cursor/rules/`: +**After upstream updates:** -1. `test-driven-development.md` — TDD workflow and Prove-It pattern -2. `code-review-and-quality.md` — Five-axis review -3. `incremental-implementation.md` — Build in small verifiable slices +```bash +rsync -a /path/to/agent-skills/skills/ .cursor/skills/ +``` -### Phase-Specific Skills (Load on Demand) +Each skill folder must contain `SKILL.md` with YAML frontmatter, at minimum: -For phase-specific work, create additional rule files as needed: +```yaml +--- +name: test-driven-development +description: Drives development with tests. Use when implementing logic, fixing bugs, or changing behavior. +--- +``` -- `spec-development.md` -> `spec-driven-development/SKILL.md` -- `frontend-ui.md` -> `frontend-ui-engineering/SKILL.md` -- `security.md` -> `security-and-hardening/SKILL.md` -- `performance.md` -> `performance-optimization/SKILL.md` +Cursor uses `description` (and related metadata) to decide when to apply a skill. -Add these to `.cursor/rules/` when working on relevant tasks, then remove when done to manage context limits. +### 2. Add minimal project rules (optional but useful) -## Usage Tips +Create `.cursor/rules/agent-skills.mdc`: -1. **Don't load all skills at once** - Cursor has context limits. Load 2-3 essential skills as rules and add phase-specific skills as needed. -2. **Reference skills explicitly** - Tell Cursor "Follow the test-driven-development rules for this change" to ensure it reads the loaded rules. -3. **Use agents for review** - Copy `agents/code-reviewer.md` content and tell Cursor to "review this diff using this code review framework." -4. **Load references on demand** - When working on performance, add `performance.md` to `.cursor/rules/` or paste the checklist content directly. +```markdown +--- +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//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:** + +```markdown +--- +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//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//`? 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 + +- [getting-started.md](getting-started.md) +- [../README.md](../README.md) — Cursor quick blurb +- Upstream: [github.com/addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)