runner

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:

1. 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
   

2. When prompted to allow commands (e.g., "Add Shell(cd), Shell(make) to allowlist?"), approve them