| name | rule-writer |
| description | Author Cursor rules correctly: Project Rules (.mdc frontmatter), User Rules (draft for user paste only), Team Rules, and AGENTS.md; apply modes, globs, precedence, dual-store pitfalls. Use when creating or editing .cursor/rules, User Rules, Team Rules, AGENTS.md, alwaysApply/globs frontmatter, /create-rule, or Import Remote Rule. Triggers: rule writer, cursor rules, create rule, .mdc rule, alwaysApply, project rules, user rules, team rules, AGENTS.md, remote rule import. |
| metadata | {"pattern":"generator","domain":"meta","version":"1.1"} |
Rule writer
Teach agents to author Cursor rules from Cursor Rules docs. Condensed tables: references/cursor-rules-docs.md. Prose quality: prompt-writing-discipline.
Built-in create-rule (skills-cursor) is a thin scaffold; this skill is the accurate docs + store workflow.
When invoked
- Clarify store (ask if unclear): Project | User (Settings paste) | Pack
.mdc | Team (dashboard) | AGENTS.md.
- Review existing rules in the target location; extend or split instead of duplicating.
- Draft thin, actionable content (prefer <120 lines for alwaysApply; docs allow <500).
- Set frontmatter for Project / pack
.mdc only (tables below).
- Write only to agent-writable stores; for User Rules, draft text for the user to paste (see below).
Four rule types
| Type | Where | Agent may write? | Notes |
|---|
| Project Rules | Workspace .cursor/rules/*.mdc | Yes | Version-controlled; frontmatter controls apply |
| User Rules | Customize -> Rules -> User Rules | No (paste only) | Global freeform; Agent Chat only -- not Ctrl/Cmd+K |
| Team Rules | Cursor dashboard | No (admins UI) | Team/Enterprise; freeform (+ optional globs); can be enforced |
| AGENTS.md | Project root and/or nested dirs | Yes | Plain markdown; no frontmatter; nested combine, more specific wins |
Stores (MUST clarify)
These are not the same thing:
| Store | Path / UI | What it is | Agent action |
|---|
| Settings User Rules | Customize -> Rules -> User Rules | One global freeform blob (IDE-only / online Settings) | Draft markdown; user copy/pastes into the field and saves |
Pack ~/.cursor/rules/*.mdc | ~/.cursor/rules/ (source also in pack rules/) | Optional pack convention -- not the Settings UI | Edit pack / compose paste buffer; do not silent-write Settings |
| Project Rules | <workspace>/.cursor/rules/*.mdc | Repo-scoped | Agent edits .mdc files directly |
MUSTNOT put the same normative text in Settings User Rules and an alwaysApply: true pack/project .mdc if both load -- double injection.
User Rules workflow (MUST / MUST NOT)
Aligned with docs: User Rules = global preferences in Customize -> Rules.
MUST NOT
- Do not write
aicontext.personalContext, patch state.vscdb, or use AppData / SQLite / other storage hacks to "set User Rules".
- Do not claim Settings were updated, or that the agent applied User Rules programmatically.
- Do not treat pack
~/.cursor/rules/*.mdc as equivalent to Settings User Rules.
MUST
When the user asks to create or revise User Rules:
- Produce a clean markdown block (the full intended User Rules text).
- Tell the user to open Customize -> Rules -> User Rules, replace the field with that text, and save.
- Optionally write the same text to a helper file such as
user-rules-settings-composed.txt (workspace or pack) only as a copy/paste aid -- never as "Settings updated".
Closing instruction (example)
After drafting, end with something like:
Copy the block below into Customize -> Rules -> User Rules, replace the whole field, then save.
...drafted User Rules...
Project rule mechanics
- Extension must be
.mdc. Plain .md under .cursor/rules is ignored (no frontmatter). Prefer AGENTS.md for plain markdown.
- Frontmatter fields:
description, globs, alwaysApply.
- Folders under
.cursor/rules/ are fine (e.g. frontend/components.mdc).
Apply modes (UI type -> behaviour)
| Rule type (UI) | Effect |
|---|
| Always Apply | Every chat session |
| Apply Intelligently | Agent pulls in when description matches relevance |
| Apply to Specific Files | Auto-attach when a matching file is in context |
| Apply Manually | Only when @-mentioned (e.g. @my-rule) |
Frontmatter interaction
alwaysApply | description | globs | Behaviour |
|---|
true | -- | -- | Always included; globs and description ignored |
false | -- | provided | Auto-attached when a matching file is in context |
false | provided | omitted | Agent uses description; includes when relevant |
false | omitted | omitted | Manual @-mention only |
Minimal templates
Always apply:
---
alwaysApply: true
---
- Concrete MUST / MUSTNOT lines only
Globs:
---
globs: src/**/*.tsx
alwaysApply: false
---
- File-scoped conventions
Intelligent:
---
description: When this topic applies (be specific)
alwaysApply: false
---
- Topic-scoped guidance
Manual:
---
alwaysApply: false
---
- Checklist used only via @-mention
Multiple globs: comma-separated (docs/**/*.md, docs/**/*.mdx). See reference for pattern examples.
Creating rules
- Project: Chat
/create-rule or Customize -> Rules -> Add Rule (writes under .cursor/rules). Agent may edit those .mdc files.
- User Rules: Agent drafts only; user pastes into Customize -> Rules -> User Rules (see workflow above).
- Remote: Customize -> Rules -> Add Rule -> Remote Rule (Github) -> URL; lands under
.cursor/rules/imported/... (relative paths preserved).
- Team: dashboard only (admins); not a local
.mdc file.
Precedence
When guidance conflicts: Team Rules -> Project Rules -> User Rules. All applicable rules still merge; earlier source wins on conflict.
Best practices
- Under 500 lines per rule (prefer <120 for alwaysApply / thin-mdc).
- Split large topics into composable rules.
- Concrete examples or
@file references; do not paste whole files that go stale.
- Avoid style-guide dumps, exhaustive CLI lists, and rare edge cases -- use linters / point at canonical code.
- Add rules when Agent repeats a mistake; check into git for Project Rules.
AGENTS.md
- Root and nested
AGENTS.md supported; nested apply for that directory tree; more specific overrides broader.
- Use when instructions are simple and frontmatter/apply modes are unnecessary.
FAQ (docs)
- Intelligent mode needs a real
description; glob mode needs patterns that match files in context.
- Rules do not affect Cursor Tab or other non-Agent features.
- User Rules do not apply to Inline Edit (Ctrl/Cmd+K).
Checklist before finish
