Cursor Setup: Skills, Rules, and Commands

Cursor is our primary AI-assisted editor. We use three mechanisms to shape how the assistant behaves: rules, skills, and commands. Each has a specific role.

Rules (.cursor/rules/*.mdc)

Rules are always-on constraints. They apply when the assistant is working in matching paths (e.g. src/**/*.ts). They answer: “What must always be true in this codebase?”

Examples we use:

• Ports and adapters — No direct adapter imports in app code; ESLint enforces boundaries.
• No magic strings — Domain concepts live in typed constants; rules point to where.
• Service contracts — Services are interfaces; errors come from *.errors.ts.
• Documentation contracts — When you touch an endpoint, you update API docs; when you touch a command, you update command docs.
• Linear workflow — Work on a branch per issue; commits reference the issue key; PRs use the right token.
• GitHub token — Use PERSONAL_GITHUB_TOKEN for gh so org vs personal access is explicit.

Rules are written in Markdown with optional YAML frontmatter (e.g. globs, alwaysApply). They’re the “law” of the project so the assistant doesn’t have to guess.

Skills (.cursor/skills/*.md)

Skills are multi-step procedures the assistant can run when the user asks for something specific. They answer: “When I want to do X, what are the exact steps?”

Examples we use:

• generate-api-docs — Regenerate API docs from endpoint source.
• generate-command-docs — Regenerate command docs from command modules.
• author-customer-docs — Create or update customer-facing docs by persona.
• renovate-upgrade-validation — How to validate a Renovate dependency upgrade PR.

Each skill document describes “when to use,” “steps,” and often “output format” or “conventions.” The assistant is instructed to follow the skill when the user’s request matches. Skills are parallelizable where it makes sense (e.g. different doc types can be generated in parallel by subagents).

Commands (.cursor/commands/*.md)

Commands are one-shot workflows triggered by name (e.g. from the command palette or a shortcut). They answer: “What’s the exact flow for this discrete task?”

Examples we use:

• workon — Start working on a Linear issue (branch, state, assignee, plan).
• openpr — Open a PR with the right base, token, and body.
• createissue — Create a Linear issue with labels and context.
• syncblueprint, watchbuild, taillogs — Render and deployment helpers.

Commands are often thin wrappers around scripts in devtools/ or package.json; the command doc tells the assistant (or the user) how to invoke them and what to expect.

How they work together

1. Rules constrain every edit in scope—no exceptions unless the user explicitly overrides.
2. Skills are invoked when the user says “generate API docs” or “update command docs”; the assistant follows the steps in the skill.
3. Commands are invoked when the user runs a named command; the assistant (or user) follows the command doc.

New rules, skills, or commands should be listed in the Reference. Run pnpm docs:ai-ecosystem:generate after adding or changing any of them so the index stays current.