# Cursor SDK Skills
Agent skills for building with [Cursor](https://cursor.com) — the [TypeScript SDK](https://cursor.com/docs/sdk/typescript), the [CLI](https://cursor.com/docs/cli/overview), and the project-level configuration the SDK and CLI both load (`.cursor/rules/`, `.cursor/skills/`, `.cursor/hooks.json`, `.cursor/mcp.json`, `AGENTS.md`).
Built as a **skill graph**: every `SKILL.md` is a Map of Content with short node descriptions and `[[wikilinks]]` to atomic concept files in `references/`. Skills cross-link freely — treat all eleven as one larger graph.
## Install
```bash
npx skills add HKTITAN/cursor-sdk
```
This uses the [skills.sh](https://skills.sh) CLI to install the skills into your detected agent (Claude Code, Cursor, etc.). The CLI prompts for scope (project vs. global) and method (symlink vs. copy).
## Paste this into your coding agent
Drop the block below into your agent's instructions / `AGENTS.md` / `.cursor/rules/` / system prompt:
```
You have access to Cursor SDK Skills — the authoritative reference for building
with the Cursor TypeScript SDK, the `agent` CLI, and the project-level config
files both runtimes load (.cursor/rules, .cursor/skills, .cursor/hooks.json,
.cursor/mcp.json, AGENTS.md). Always consult these before writing Cursor code.
- Repo: https://github.com/HKTITAN/cursor-sdk
- Skills root: https://github.com/HKTITAN/cursor-sdk/tree/main/skills
- Install: npx skills add HKTITAN/cursor-sdk
- Authoring rules and conventions: AGENTS.md at the repo root.
Each skill is a graph:
- `skills/<skill>/SKILL.md` is a Map of Content — descriptions plus [[wikilinks]].
- `skills/<skill>/references/<topic>.md` are atomic concept nodes.
- Cross-skill links use `[[../<other-skill>/references/<node>]]`.
The eleven skills:
- cursor-sdk — install, auth, Agent.create / resume / prompt, lifecycle
- cursor-runs — send, stream, SDKMessage taxonomy, conversation, wait, cancel
- cursor-cloud — cloud runtime, repos, auto-PR, artifacts, reattach
- cursor-mcp — MCP server config (stdio / http / sse), inline vs file
- cursor-subagents — `agents` field, AgentDefinition, MCP scoping, model inheritance
- cursor-models — Cursor.models.list, ModelSelection, parameters, sticky overrides
- cursor-hooks — .cursor/hooks.json gates, programmatic alternatives
- cursor-errors — CursorAgentError hierarchy, isRetryable, retry pattern
- cursor-rules — .cursor/rules/*.mdc, AGENTS.md, rule types, settingSources loading
- cursor-skills-system — .cursor/skills/, SKILL.md spec, skill-graph pattern
- cursor-cli — `agent` CLI: install, modes, headless, GitHub Actions
External authoritative docs (only after consulting the skills):
- SDK reference: https://cursor.com/docs/sdk/typescript
- All Cursor docs: https://cursor.com/docs
- Agent Skills: https://agentskills.io/specification
Rules:
1. Before recommending a method, parameter, env var, CLI flag, or rule
frontmatter field, read the relevant skill node and verify. Cite the node
path you used (e.g. `skills/cursor-runs/references/stream.md`).
2. Never invent SDK methods, CLI flags, or feature names. If the skills don't
cover it, say so and ask — don't guess from training data.
3. Prefer reading the specific `references/<node>.md` over the whole SKILL.md
when you know the area — it's cheaper on context and the graph is built
for exactly this kind of traversal.
4. The SDK, the CLI, and the editor share a runtime — when something works in
one, check the corresponding skill before assuming the same shape applies.
Inline mcpServers and the `agents` field are NOT persisted across
Agent.resume; rules and skills travel with the repo, not with the agent.
```
## What's included
| Skill | Use it when… |
|---|---|
| `cursor-sdk` | Bootstrapping any program that imports `@cursor/sdk` — install, auth, lifecycle |
| `cursor-runs` | Consuming agent output, multi-turn conversations, streaming, cancellation |
| `cursor-cloud` | Running long, repo-modifying, PR-producing agents off the local machine |
| `cursor-mcp` | Adding tools to an agent via MCP servers — stdio, HTTP, SSE |
| `cursor-subagents` | Decomposing work across specialist personas via the `agents` field |
| `cursor-models` | Picking models, tuning parameters, routing workload classes |
| `cursor-hooks` | File-based pre/post gates and programmatic-callback alternatives |
| `cursor-errors` | Classifying SDK failures and building retry logic |
| `cursor-rules` | Authoring `.cursor/rules/*.mdc` and `AGENTS.md` the SDK loads |
| `cursor-skills-system` | Authoring `.cursor/skills/` packs the SDK / CLI / editor pick up |
| `cursor-cli` | Scripting Cursor in shells, CI, and GitHub Actions |
## Structure: skill graphs, not flat files
Each skill is a **graph**, not a single file:
- **`SKILL.md`** is a *Map of Content* — short descriptions of every node in the graph, plus `[[wikilinks]]` to follow.
- **`references/*.md`** are atomic concept files — one complete thought each, with their own YAML frontmatter and outbound `[[wikilinks]]` to siblings (within the skill) and across skills. (`references/` is the [Agent Skills spec](https://agentskills.io/specification) standard directory for additional documentation.)
- The agent **scans descriptions and frontmatter first**, then follows only the links it needs. Most decisions happen before reading a single full node.
- Cross-skill wikilinks (e.g. `[[../cursor-runs/references/stream]]`) make all eleven skills navigable as one larger graph.
## The skill graph
```
cursor-sdk ──────────────── cursor-models
(entry, lifecycle) (catalog, params,
│ routing, sticky)
│
┌─────────────┼─────────────┐
│ │ │
cursor-runs cursor-cloud cursor-mcp
│ │ │
└──────┬──────┴──────┬──────┘
│ │
cursor-subagents cursor-hooks
│ │
│ │
cursor-errors cursor-rules ── cursor-skills-system
│ │
└──── cursor-cli ──┘
(shares runtime,
rules, skills,
hooks, mcp)
```
## Repository layout
```
cursor-sdk/
├── README.md # this file
├── AGENTS.md # authoring rules for contributors / agents
├── LICENSE # MIT
├── .gitignore
├── .markdownlint.jsonc
├── .github/workflows/validate.yml # markdownlint + wikilink + frontmatter checks
├── scripts/
│ └── check-wikilinks.mjs # broken-link checker used by CI
└── skills/
├── cursor-sdk/ SKILL.md + 9 references
├── cursor-runs/ SKILL.md + 14 references
├── cursor-cloud/ SKILL.md + 9 references
├── cursor-mcp/ SKILL.md + 8 references
├── cursor-subagents/ SKILL.md + 6 references
├── cursor-models/ SKILL.md + 6 references
├── cursor-hooks/ SKILL.md + 3 references
├── cursor-errors/ SKILL.md + 10 references
├── cursor-rules/ SKILL.md + 9 references
├── cursor-skills-system/ SKILL.md + 7 references
└── cursor-cli/ SKILL.md + 12 references
```
## Get an API key
Create one at [cursor.com/account](https://cursor.com/account) and export it:
```bash
export CURSOR_API_KEY="cur_..."
```
The same key works for the SDK, the CLI, and CI environments. Service account keys are supported; Team Admin keys are not yet supported.
## Validation
CI (`.github/workflows/validate.yml`) runs on every PR:
- **markdownlint** — basic markdown hygiene (config in `.markdownlint.jsonc`)
- **wikilink check** — every `[[link]]` in `skills/**/*.md` resolves to a real file (`scripts/check-wikilinks.mjs`)
- **name consistency** — `name:` in each `SKILL.md` matches its parent directory
- **required frontmatter** — `name` and `description` present on every `SKILL.md`
Locally:
```bash
npx markdownlint-cli2 "**/*.md" "!**/node_modules/**"
node scripts/check-wikilinks.mjs
```
See [AGENTS.md](AGENTS.md) for full authoring conventions.
## References
- Cursor SDK reference: <https://cursor.com/docs/sdk/typescript>
- Cursor SDK announcement: <https://cursor.com/blog/typescript-sdk>
- Cursor CLI: <https://cursor.com/docs/cli/overview>
- All Cursor docs: <https://cursor.com/docs>
- Agent Skills spec: <https://agentskills.io/specification>
- skills.sh CLI: <https://skills.sh>
- Skill-graph pattern: [@akshay_pachaar](https://x.com/akshay_pachaar)
## License
MIT