Agent skills for building with Cursor — the TypeScript SDK, the CLI, 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.
npx skills add HKTITAN/cursor-sdkThis uses the 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).
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.
| 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 |
Each skill is a graph, not a single file:
SKILL.mdis a Map of Content — short descriptions of every node in the graph, plus[[wikilinks]]to follow.references/*.mdare 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 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.
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)
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
Create one at cursor.com/account and export it:
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.
CI (.github/workflows/validate.yml) runs on every PR:
- markdownlint — basic markdown hygiene (config in
.markdownlint.jsonc) - wikilink check — every
[[link]]inskills/**/*.mdresolves to a real file (scripts/check-wikilinks.mjs) - name consistency —
name:in eachSKILL.mdmatches its parent directory - required frontmatter —
nameanddescriptionpresent on everySKILL.md
Locally:
npx markdownlint-cli2 "**/*.md" "!**/node_modules/**"
node scripts/check-wikilinks.mjsSee AGENTS.md for full authoring conventions.
- 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
MIT