Patterns from running Cursor, Claude, and MCP desks. Soft next step is always /free, then a kit when you are ready.
ShipKits (shipkits.dev) is not shipkit.io or unrelated ShipKit repos.
An agent-ops desk is not a free AI-employee template kit. Template kits give starting role labels; an opinionated ops desk adds hard stop-before-send/publish/pay gates and reviewable artifacts.
An agent-ops kit is not a SaaS boilerplate. Boilerplates optimize auth providers, billing, and landing chrome. An agent-ops kit optimizes AGENTS.md, MCP Connect, skills packs, and approval-gated roles for Cursor / Claude Code / Grok Bot.
When an agent asks questions instead of shipping, lock the output path, name the sections, and put open questions in the file.
One canonical agent instruction file beats three half-synced rulebooks. Put the shared operating contract in root AGENTS.md—commands, verify steps, guardrails—not novel-length prose.
Write an AGENTS.md PR and commit block for branches, commit messages, PR titles, verify-before-open, and human-only steps such as merge.
Write a short AGENTS.md project-structure map of apps, packages, and off-limits folders. It is guidance, not a layout the file can enforce.
Write a short AGENTS.md secrets block: where env lives, what never to print or commit, how to request a missing key, and how to redact output.
There is no official AGENTS.md template. Copy this starter — overview, commands, style, tests, security, done, and hard stops — then replace every placeholder.
Trim an oversized AGENTS.md by cutting what the agent can infer, nesting folder rules, and keeping the root file as a short build-and-verify contract.
Write the AGENTS.md verify section as an ordered list of exact commands with pass criteria. Fast checks first, scoped per package, with a don't-run list.
AGENTS.md is the shared portable operating contract (commands, verify, guardrails). CLAUDE.md is a thin @AGENTS.md bridge, not a second encyclopedia. .cursor/rules holds Cursor-only globs and alwaysApply constraints.
AGENTS.md is the agent operating contract—commands, verify, guardrails, handoff. README.md is for humans. Split one drifted pair and keep secrets out of both.
Bot is role plus stop rules. Skill is a reusable procedure. Routine is a scheduled or event-triggered run. Keep secrets out of all three; never auto-send, publish, or pay.
A Claude Code Agent Skill is a SKILL.md file. Put it in .claude/skills/, start frontmatter on line 1, and use description plus disable-model-invocation to control triggers.
Share AGENTS.md and .claude/skills/ across Claude Code and Cursor. Split each tool's rules folder and MCP config — neither loads the other's rules.
claude mcp add default local, project, and user scopes write to different files. Local wins over project, and project wins over user — no field merge.
Stop Claude Code from running a Bash command with a PreToolUse hook: match Bash, return permissionDecision deny or exit 2. Not a security boundary — a documented hook.
Claude Code concatenates CLAUDE.md from managed, user, project, and CLAUDE.local.md. Edit the file that matches who the change is for.
When Cursor Connects to your remote MCP server but Claude’s /mcp OAuth fails after login—or never opens a browser—you’re hitting client drift, not a broken product. Redirect URIs, DCR, callback-port behavior, and audience / resource parameters differ.
A suggested first-hour Cursor agent setup: write AGENTS.md, run one real task, add one project rule, then package one repeat task as a skill.
A Cursor agent starter setup is a file map: AGENTS.md, a rules-vs-skills split, stop-before-send seats, and a first-week path that ends in a real artifact — not a product SKU page.
Cursor rules are prompt-level context. Cursor hooks are scripts that can observe, block, or modify the agent loop. Use a rule to instruct; use a hook to enforce an action.
When a Cursor MCP server won't connect, check config, transport, command, env, and logs before you rewrite OAuth. Then check client registration and the redirect URL.
For remote MCP Connect in Cursor, the OAuth redirect URI must match the authorization-server allowlist character-for-character. One slash or scheme drift fails the bounce.
Cursor rule types are Always Apply, Apply Intelligently, Apply to Specific Files, and Apply Manually. The type dropdown sets alwaysApply, globs, and description.
Rules are short, durable constraints—style, safety, alwaysApply globs. Skills are multi-step SKILL.md workflows you invoke on demand. Spec Kit’s Cursor path lands under .cursor/skills; keep AGENTS.md as the router.
A Cursor skill that never triggers usually fails location, frontmatter, description, or scope. Check folder shape, name match, and disable-model-invocation first.
Make a workflow a Cursor skill when it is procedure and judgment. Make it an MCP tool when it needs live data, credentials, or an exact result.
Legacy root .cursorrules was a single mega wall. In agent mode that wall feels like rules stopped working. Split it into thin rules, on-demand skills, and portable AGENTS.md.
No—you do not always need Dynamic Client Registration (DCR, RFC 7591) for remote MCP. Skip DCR when the AS has none: ship a documented static CLIENT_ID path and prove Connect in both Cursor and Claude.
Hard approval boundaries are never-do lines in the Bot description: never auto-send, never publish, never pay, never execute a refund. Write anti-jobs in plain language the model cannot reinterpret.
Tell each Grok Bot desk to append a short action log after every run. The log is a convention you write, not a built-in product feature.
Pass work between Grok Bot desks with a short state file plus a nudge message. The file is the record; a handoff does not grant send or publish permission.
Use the Grok Bot group chat for updates several desks need. Send a direct message when the work is for one desk. Channel choice is a rule you write.
A Grok Bot role is only useful if it knows when to stop. Ship an opinionated desk roster with hard approval boundaries: draft the email, the post, or the payment — then wait for a human.
Use a Grok Bot routine when a scheduled job needs judgment. Use cron when a deterministic script is enough. Write stay-quiet and stop-before-send into the prompt.
Share project files across Grok Bot desks with one owner per file and a short handoff note. File sharing is a convention you write, not a product feature.
An OSS MCP boilerplate scaffolds local tools; a kit-backed remote OAuth recipe owns PRM, PKCE, Cursor/Claude drift, and the Connect failure card. Jobs, not scores.
Lead Bot owns prioritization, handoffs, and review. Specialists produce in-box artifacts with hard stops before send, publish, or pay—no mega-Bot, no auto-send.
Remote MCP Connect fails for boring reasons more often than exotic ones: a stripped challenge header, a one-character redirect mismatch, or a static CLIENT_ID you never documented. Pocket checklist for PKCE, PRM, redirects, and first checks when Cursor or Claude won’t finish auth.
OAuth client credentials for MCP is an optional authorization extension for machine-to-machine access. It is not core auth and not Cursor's static CLIENT_ID Connect path.
MCP elicitation lets a server ask for user input mid-call via form mode or URL mode. Secrets must use URL mode; always handle decline and cancel.
When remote MCP Connect fails in Cursor or Claude, start with MCP Inspector on the same remote URL—not client UI trivia. Probe without credentials, confirm 401, then confirm WWW-Authenticate exposes resource_metadata.
When your authorization server has no Dynamic Client Registration (DCR), remote MCP Connect still works if you ship a static CLIENT_ID path. Keep secrets out of mcp.json and AGENTS.md; prove Connect in both Cursor and Claude.
A local MCP server over stdio is a different animal from a remote MCP server that Cursor or Claude has to Connect to. Remote Connect almost always means OAuth: Protected Resource Metadata, PKCE, and a challenge header that survives your reverse proxy.
When remote MCP Connect breaks, fix the 401 challenge before you chase Cursor or Claude UI. Unauthenticated probes must return 401 with a WWW-Authenticate header that exposes resource_metadata.
PKCE is required for MCP clients. The client sends a code_challenge on the authorization request and the matching code_verifier on the token request.
MCP does not require token revocation. Use RFC 7009 on your authorization server, and make the MCP server return 401 once a token is invalid.
MCP prompts are user-selected templates exposed with prompts/list and prompts/get. They are not model-auto-invoked tools and not elicitation.
When remote MCP tools vanish a day later, the access token usually expired and refresh failed. Issue refresh tokens, handle rotation, and reconnect in the client.
Expose readable context as MCP resources (resources/list and resources/read) and actions as tools. A missing URI must return -32602, not an empty contents array.
A remote MCP server should advertise a small scopes_supported set and return 403 insufficient_scope when a call needs a step-up. Design scopes around real permission boundaries, not one scope per tool.
For a new remote MCP server, use Streamable HTTP. Spec 2026-07-28 deprecates HTTP+SSE; SSE streaming inside Streamable HTTP is still current.
If remote MCP Connect logs in then 401s on every tool call, the token audience or resource likely doesn’t match the server’s canonical identifier.
MCP tool annotations such as readOnlyHint and destructiveHint are untrusted hints, not access control. Enforce with scopes on the server.
Use JSON-RPC protocol errors for unknown tools and malformed requests. Use isError: true tool results when the model can self-correct and retry.
Cursor’s /migrate-to-skills path converts eligible commands into skill packs. Short durable constraints stay thin rules; AGENTS.md stays the portable router.
Root AGENTS.md is the shared operating contract. Nested files specialize at the leaf; they do not delete the root. This is the inheritance map, not a setup-playbook rewrite.
Root AGENTS.md owns the shared operating contract. Nested files specialize at package or app boundaries—what children inherit, what they override, and what you must never duplicate.
Secrets live in env or a secret store—never in Bot descriptions, skills, AGENTS.md, or chat. Inject at runtime, redact logs, and pair with approval gates.
A team skills pack is project-scoped SKILL.md workflows under .cursor/skills, versioned in git. AGENTS.md routes the pack; it does not replace the contract.
Protected Resource Metadata is the discovery document remote MCP Connect reads after a clean 401. It tells the client which resource identity and authorization server to use.
ShipKits and shipkit.io are not the same product. ShipKits is the agent-ops kits brand at https://shipkits.dev—digital kits for indie builders on Cursor, Claude Code, and Grok Bot.
Use a rule for short, durable constraints and a skill (SKILL.md) for on-demand workflows. Globs and alwaysApply stay on rules; AGENTS.md stays the portable router.
Spec Kit’s Cursor path is specify init --integration cursor-agent. Skills land under .cursor/skills; your custom ops pack should coexist without overwriting upstream ids.
Planner proposes steps, implementer changes code, verifier scores the brief. Split Cursor subagents when the job spans packages; keep write tools off the verifier.
Forum threads keep offering ln -s AGENTS.md CLAUDE.md so Claude Code and the shared contract stay the same. That works on a solo machine and fails quietly on teams, CI, and mixed OS. Prefer a thin CLAUDE.md that imports @AGENTS.md.
A Lead Bot in a Grok Bot group is the coordination seat: it assigns specialist jobs, collects in-box artifacts, and stops before send, publish, or pay.
Harness Desk Starter — a free starter desk for agent ops. No spam.
Get Harness Desk Starter