Cursor Ide Weapon

cursor-ide Weapon

The knowledge repository for cursor-ide-guardian. Covers every platform surface of Cursor IDE: rule files, MCP integration, SDK authoring, Agents Window workflows, and productivity patterns.

When this weapon applies

Load whenever cursor-ide-guardian is invoked. Typical triggers (any of these phrases, even without naming Cursor explicitly):

• "review my .cursorrules" / "migrate my rules to MDC"
• "add an MCP server" / "register a custom tool in Cursor"
• "build an automation with the Cursor SDK" / "Agent.create" / "@cursor/sdk"
• "create a custom mode" / "design a Cursor mode for X"
• "background agents" / "cloud agents" / "Agents Window" / /multitask
• "Cursor keybindings" / "Cursor shortcuts" / "power user Cursor"
• "Cursor plugin" / "Cursor extension"

Do NOT load for:

• Code quality produced by Cursor agents (language-specific guardians).
• Prompt engineering for OpenAI / Anthropic / etc. (mind-guardian).
• CI/CD pipelines that orchestrate Cursor SDK (devops-guardian owns the pipeline; this weapon authors the SDK code itself).

First action when loaded

Read in order before acting:

1. guides/01-principles.md — rule file philosophy, context budget constraints, the MDC vs .cursorrules decision, activation mode taxonomy. This is the mental model foundation.
2. guides/02-rule-file-authoring.md — full frontmatter spec, glob patterns, migration checklist from legacy .cursorrules, anti-patterns.
3. Then pull the task-specific guide: 03 for MCP, 04 for SDK, 05 for modes/productivity, 06 for extensions.

Folder layout

cursor-ide-weapon/
+- SKILL.md                          (this file — master index)
+- guides/
|  +- 01-principles.md               (philosophy: rule activation, context budget, MDC vs legacy)
|  +- 02-rule-file-authoring.md      (frontmatter spec, glob patterns, migration)
|  +- 03-mcp-integration.md          (mcp.json schema, tool authoring, OAuth, Extension API)
|  +- 04-sdk-api.md                  (Agent lifecycle, run.stream, errors, local vs cloud)
|  +- 05-modes-and-productivity.md   (custom modes, Agents Window, keybindings, slash commands)
|  +- 06-extension-development.md    (plugin manifests, quality gates, marketplace checklist)
+- examples/
|  +- rule-file-examples.md          (worked .mdc examples for common scenarios)
|  +- mcp-server-example.md          (minimal TypeScript MCP server + mcp.json entry)
|  +- sdk-agent-example.md           (create, stream, error-handle pattern)
+- templates/
|  +- rule-file-template.mdc         (canonical .mdc frontmatter template)
|  +- mcp-json-template.json         (mcp.json with both stdio and remote stubs)
|  +- sdk-script-template.ts         (Agent.create + run.stream + error handling)
+- reports/
|  +- README.md
+- research/                         (populated by scripture-historian, 18 files)
   +- research-plan.md
   +- research-summary.md
   +- index.md
   +- internal/  (4 files)
   +- external/  (11 files)

Critical directives (lifted from the Command Brief)

These are weapon-level non-negotiables that cursor-ide-guardian must enforce on every invocation:

• Check Cursor version before referencing features. Why: Cursor ships weekly; Cloud Agents, Agents Window, and SDK capabilities are version-gated. Use Cursor 3 (April 2026+) as the modern baseline.
• Never write .cursorrules for a project already using .cursor/rules/. Why: .cursorrules is silently ignored in Agent mode and the two formats produce silent precedence conflicts.
• MCP tools must have explicit JSON Schema for every parameter. Why: Cursor silently rejects tools with malformed schemas with no UI feedback.
• Prefer alwaysApply: false with narrow globs over alwaysApply: true. Why: alwaysApply: true rules consume the shared context budget (2,000-token cap across all alwaysApply rules).
• Always show CursorAgentError handling in SDK examples. Why: SDK runs fail silently without it.

Key facts by domain (quick reference)

Rules

Four MDC activation modes (frontmatter drives which one applies):

Budget: keep total alwaysApply: true content under ~2,000 tokens across all rule files.

MCP

Config hierarchy: project .cursor/mcp.json > global ~/.cursor/mcp.json (same-name project wins). Restart Cursor after editing either file. Tool auto-approval is off by default (Settings > MCP > allow tool auto-run). Interpolation variables: ${env:NAME}, ${userHome}, ${workspaceFolder}, ${workspaceFolderBasename}, ${pathSeparator}.

SDK (@cursor/sdk >= 1.0.7, public beta April 29, 2026)

const agent = await Agent.create({ local: { cwd, model: "claude-sonnet-4-5" } });
const run = agent.send("do X");
for await (const msg of run.stream()) {
  if (msg.type === "assistant") process.stdout.write(msg.text ?? "");
}
await run.wait(); // resolves RunResult
await agent.dispose();

Error handling: all errors extend CursorAgentError { isRetryable, code }. Cloud agents: one active run at a time — watch for AgentBusyError (code: agent_busy, isRetryable: false).

Agents Window (Cursor 3, April 2026)

• Background Agents renamed to Cloud Agents in Cursor 3.
• Agents Window: unified sidebar for all agents (local, cloud, mobile, Slack, GitHub, Linear).
• Agent Tabs: tiled multi-pane layout (added April 13, 2026).
• /multitask: async parallel subagents within a single task.
• Cloud Agents: isolated Ubuntu VMs, dedicated agent/ branch, auto-PR on completion.

Open questions (from research)

1. Plan tier detection from SDK: No documented public API for detecting Free / Pro / Business / Enterprise from within an SDK run. Flag as "not publicly documented" in guide 04.
2. MCP tool name length: No specific Cursor-documented limit found; best practice is <64 chars, namespace with server-name.tool-name.
3. Custom modes file format: .cursor/modes.json was "under consideration" as of May 2026; current method is UI-only (Settings > Features > Chat > Custom Modes). Do not document the file path until confirmed.
4. Extension guide source gap: vscode.cursor.plugins.registerPath Extension API found; full manifest schema needs direct fetch from cursor.com/docs/plugins.

Refresh cadence

• Guides 01-05: refresh every 3 months or on any Cursor major version.
• Guide 06: refresh when extension/plugin manifest format changes.
• Research folder: re-run scripture-historian at shallow tier on any Cursor major release.

Pairing

Forged by weapon-forge from cursor-ide-guardian-command-brief.md and research/. Part of the Legion AI Tools Factory by Mario Aldayuz a.k.a @thenotoriousllama.