Sub-Agents Skills
Orchestrate any LLM as a sub-agent from any AI coding tool.
Use Codex, Claude Code, Cursor CLI, and Gemini CLI as sub-agents within a single workflow — regardless of which tool you're running. Define task-specific agents once in markdown, and execute them on any backend.
graph LR
A["Your AI tool<br/>(Codex, Claude Code, Cursor...)"] --> B["run_subagent.py"]
B --> C["Codex"]
B --> D["Claude Code"]
B --> E["Cursor CLI"]
B --> F["Gemini CLI"]
style B fill:#f5f5f5,stroke:#333
Why?
Most major AI coding agents now have built-in sub-agents — but only for their own model. Claude Code delegates to Claude. Codex delegates to GPT. None of them let you call a competitor's model.
This skill removes that restriction:
- Cross-LLM orchestration — Use Codex for fast refactors, Claude Code for long-chain reasoning, and Gemini CLI for large-context analysis, all from the same parent session.
- No vendor lock-in — Your agent definitions are plain markdown files that work with Codex, Claude Code, Cursor CLI, Gemini CLI, VS Code, and 30+ other tools that support the Agent Skills format, so switching IDEs or LLM providers doesn't mean rewriting your workflow.
- Bring Your Own Model — Choose which model handles each task and pay each provider directly at their API rates.
- Team portability — Share agent definitions across your team regardless of IDE or preferred LLM.
Supported Backends
Each agent definition specifies which CLI runs it via the run-agent frontmatter. You can mix backends freely within a project.
| Backend | CLI Command | Install |
|---|
| Codex (OpenAI) | codex | npm install -g @openai/codex |
| Claude Code (Anthropic) | claude | curl -fsSL https://claude.ai/install.sh | bash |
| Cursor | cursor-agent | curl https://cursor.com/install -fsS | bash |
| Gemini (Google) | gemini | npm install -g @google/gemini-cli |
You only need to install the backends you plan to use.
Quick Start
Requirements: Python 3.9+ and at least one supported backend installed.
1. Install the Skill
Codex (plugin):
codex plugin marketplace add shinpr/sub-agents-skills
Then open the plugin picker, install Runner, and restart Codex:
/plugins
After restart, invoke the skill as $runner:sub-agents.
Claude Code (plugin):
/plugin marketplace add shinpr/sub-agents-skills
/plugin install runner@sub-agents-skills
/reload-plugins
Other clients (Cursor CLI, Gemini CLI, VS Code, etc.):
Use the install script to copy the skill into the client's skill path:
# Cursor
curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target ~/.cursor/skills
# Gemini
curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target ~/.gemini/skills
# VS Code / Copilot (project-scoped)
curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target .github/skills
Or clone manually:
git clone https://github.com/shinpr/sub-agents-skills.git
cd sub-agents-skills
./install.sh --target <client-skill-path>
2. Create Your First Agent
Create a .agents/ folder in your project and add code-reviewer.md:
---
run-agent: codex
---
# Code Reviewer
Review code for quality and maintainability issues.
## Task
- Find bugs and potential issues
- Suggest improvements
- Check code style consistency
## Done When
- All target files reviewed
- Issues listed with explanations
The run-agent frontmatter specifies which CLI executes this agent. See Writing Effective Agents for more on agent design.
3. Fix "Permission Denied" Errors When Running Shell Commands
Sub-agents may fail to execute shell commands with permission errors. This happens because sub-agents can't respond to interactive permission prompts.
Recommended approach:
-
Run your CLI tool directly with the task you want sub-agents to handle:
codex # For Codex users
claude # For Claude Code users
cursor-agent # For Cursor CLI users
gemini # For Gemini CLI users
-
When prompted to allow commands (e.g., "Add Shell(cd), Shell(make) to allowlist?"), approve them
