Claude Code Subagents for Cursor
Run Cursor's custom subagents on the model in each agent file via Claude Code. Works around Cursor pinning custom subagents to the parent model.
Claude Code Subagents for Cursor
A Cursor skill that runs your custom subagents through Claude Code, so each one runs on the model: written in its own agent file instead of the parent chat's model. Invoke it with /use-claude-code-subagents.
Overview
In Cursor, custom subagents (.cursor/agents/*.md, .claude/agents/*.md, .codex/agents/*.md) declare a model: in their frontmatter, but the Task tool runs them on the parent chat's model in two cases:
- a personal Anthropic API key (BYOK) is on (confirmed by Cursor staff), or
- the agent's model is not enabled in Cursor.
An agent you set up for Haiku then bills at Opus rates. Claude Code, run headlessly from Cursor's Shell tool, does honor the model: in agent files. This skill routes custom subagents through claude -p for the rest of the chat, and every run reports the model it actually ran on.
You need: Cursor desktop running locally (Cloud Agents have no claude CLI), Claude Code installed and signed in (setup guide), and a POSIX shell (macOS, Linux). Runs bill your Claude Code account. The skill checks the Claude Code version for you.
Installation
Pick one route. All of them install the same skill.
Cursor plugin (recommended)
In Cursor, open Customize, Plugins, Add, From GitHub Repository and enter:
github.com/ysskrishna/claude-code-subagents-for-cursor
Choose user scope to get the skill in every project, or project scope to commit it for a team. More in docs/install/cursor-setup.md.
skills.sh (npx skills)
npx skills add ysskrishna/claude-code-subagents-for-cursor -a cursor -g
Installs to ~/.agents/skills/, which Cursor loads. Drop -g to install into the current project. Update with npx skills update. Remove with npx skills remove use-claude-code-subagents. More in docs/install/skills-sh-setup.md.
GitHub CLI (gh skill)
gh skill install ysskrishna/claude-code-subagents-for-cursor --all --agent cursor --scope user
Installs to ~/.cursor/skills/. Without --agent cursor, gh installs for GitHub Copilot. Update with gh skill update. More in docs/install/gh-cli-setup.md.
Manual
Copy the skills/use-claude-code-subagents folder, including references/, to ~/.cursor/skills/ (user) or <project>/.cursor/skills/ (project). More in docs/install/manual-setup.md.
Claude Code, npm, and OpenClaw
The same repo also has .claude-plugin/plugin.json, the npm package @ysskrishna/claude-code-subagents-for-cursor, and openclaw.plugin.json. These do not replace the Cursor install above. In Claude Code:
/plugin install cursor-subagent-models --marketplace ysskrishna/claude-code-subagents-for-cursor
Details: docs/install/packages.md.
Usage
/use-claude-code-subagents
The agent replies Subagent mode: claude code. From then on, each custom subagent you ask for runs through Claude Code on its own model, and the reply ends with a line like scout ran on claude-haiku-5-5. Say "use cursor subagents" to switch back to Cursor's Task tool.
More in docs/guides/usage.md: how the skill loads on its own, what to expect, and how to check it works. To try it on a ready-made project with two agents, see examples/subagents.
Run without approval prompts
Claude Code runs outside Cursor's sandbox, so pick a run mode that allows it in Cursor Settings, Agents, Approvals & Execution:
- Auto-Review (with Sandbox): suggested. Commands outside the sandbox go through a safety check.
- Run Everything (Unsandboxed): no prompts at all, for projects you trust.
The Allowlist modes are not supported: they need an entry for every command. Briefs are written to a temp folder, not your repo. Details, other prompts (MCP tools, fetch) and trade-offs: docs/guides/permissions.md.
Documentation
| Guide | What is in it |
|---|---|
| docs/README.md | Requirements, platforms, what is tested, when you do not need this |
| docs/install/packages.md | Claude Code plugin, npm package, OpenClaw bundle |
| docs/guides/usage.md | Using the skill, verifying it, what to expect |
| docs/reference/how-it-works.md | Agent lookup, model mapping, how the claude command is built |
| docs/guides/permissions.md | Run without approval prompts: Cursor run modes, Claude Code settings |
| docs/guides/troubleshooting.md | Symptoms and fixes |
| docs/reference/security.md | What the skill can do, how it is limited, what to watch for |
| docs/contributing/development.md | Check scripts, CI, releases |
Reporting a vulnerability: see SECURITY.md.
Built and maintained by
Claude Code Subagents for Cursor is built and maintained by:
| Name | GitHub | Role | |
|---|---|---|---|
![]() | Y. Siva Sai Krishna | @ysskrishna | Creator |
Changelog
See CHANGELOG for release history.
Support
If you find this library helpful:
- ⭐ Star the repository
- 🐛 Report issues
- 🔀 Submit pull requests
- 💝 Sponsor on GitHub
License
MIT © Y. Siva Sai Krishna — see LICENSE for details.
Author's GitHub • Author's LinkedIn • Author's site • Report Issues

