Sub-Agents Skills

English | 简体中文

Run task-specific agents on different AI coding backends from one parent tool.

Define each agent once in Markdown, then choose its execution backend independently. Route implementation, review, investigation, or verification to a different coding backend without rewriting the agent definition.

The skill itself follows the Agent Skills standard; the agents it runs are Markdown files under .agents/.

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

Grok Build (plugin):

grok plugin marketplace add shinpr/sub-agents-skills
grok plugin install runner --trust

Google Antigravity (plugin):

agy plugin install https://github.com/shinpr/sub-agents-skills/tree/main/plugins/runner

Other clients (Cursor 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

# VS Code / Copilot (project-scoped)
curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target .github/skills

# Gemini CLI
curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target ~/.gemini/skills

Or clone manually:

git clone https://github.com/shinpr/sub-agents-skills.git
cd sub-agents-skills
./install.sh --target 

2. Create Your First Agent

Create a .agents/ folder in your project and add code-reviewer.md:

---
run-agent: codex
permission: read-only
---

# 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 backend executes this agent. See Writing Agents for more on agent design.

3. Run It

Ask your parent AI tool:

Use the code-reviewer agent to review the authentication changes.

The parent tool invokes the agent with the selected backend and returns its result.

Why?

Most AI coding tools provide sub-agents tied to their own models. Claude Code delegates to Claude, and Codex delegates to GPT. Their built-in delegation does not provide a portable way to route a task to another provider’s model.

Sub-Agents Skills separates an agent’s role from its execution backend. The Markdown file defines what the agent does, while run-agent selects where it runs. Changing the backend does not require rewriting the role, task, or output instructions.

Because the runner is packaged as an Agent Skill, the same .agents/ definitions can be used from different supported parent tools.

Usage Examples

To run an agent, describe the task in your prompt:

Use the code-reviewer agent to check my UserService class.

Use the test-writer agent to create unit tests for the auth module.

Use the doc-writer agent to add JSDoc comments to all public methods.

Mixing Backends in One Project

Agents using different backends can live side by side:

.agents/
├── test-writer.md         # run-agent: codex
├── code-reviewer.md       # run-agent: claude
├── kimi-implementer.md    # run-agent: kimi
└── alternate-reviewer.md  # run-agent: grok

Use the code-reviewer and alternate-reviewer agents in parallel, then send the agreed changes to kimi-implementer.

Name both the agent and the task in the request; an agent name alone does not provide a task.

Supported Backends

Set run-agent in each agent definition. The value selects a backend; some backends share an underlying executable.

Install only the CLIs you plan to use. For Google models, prefer Antigravity CLI 1.1.12 or later; existing Gemini CLI configurations remain supported.

Writing Agents

Agent definitions are .md or .txt files under .agents/. For normal use, include run-agent in the YAML frontmatter and keep the task instructions in the body.

---
run-agent: claude
model: opus
effort: high
permission: safe-edit
---

# Agent Name

One-sentence purpose.

## Task
- Action 1
- Action 2

## Done When
- Criterion 1
- Criterion 2

Configuration Reference

Backend Setup

Most backends use their CLI’s existing authentication. The following backends need additional routing or provider configuration.

Security

Agent definitions are system prompts that control what the sub-agent does. A malicious agent definition could instruct the sub-agent to read sensitive files, execute harmful commands, or exfiltrate data.

Only use agent definitions you’ve written yourself or from sources you trust. Review any third-party agent definitions before use.

How It Works

The parent tool reads the installed SKILL.md, which tells it how to invoke the runner. The runner loads the selected .agents/*.md definition, calls its configured backend, and returns the result.

graph LR
    A["Your AI tool(Codex, Claude Code, Cursor...)"] --> B["run_subagent.py"]
    B --> C["Codex"]
    B --> D["Claude Code"]
    B --> E["Cursor CLI"]
    B --> H["Grok Build"]
    B --> G["GLM"]
    B --> K["Kimi"]
    B --> F["Google Antigravity(Gemini models)"]
    B -.-> GM["Gemini CLI(compatibility)"]
    B --> I["OpenCode"]
    I --> J["Configured provider/model(API · gateway · local)"]
    style B fill:#f5f5f5,stroke:#333

skills/sub-agents/
├── SKILL.md              # Instructions for the parent tool
├── scripts/
│   └── run_subagent.py   # Calls external CLIs
└── references/
    └── codex.md          # Host-specific setup notes

Independent Contexts

Each sub-agent invocation starts a fresh conversation. It does not inherit another sub-agent’s chat history, but it does share the selected working directory and its files.

The parent receives the result returned by the runner, not the sub-agent’s accumulated conversation history. Each call starts a separate CLI process and therefore has its own startup cost.

Troubleshooting

Timeout errors or authentication failures

Codex / Claude Code: Make sure the CLI is installed and accessible in your PATH.

Cursor CLI: Run cursor-agent login to authenticate, or set CURSOR_API_KEY. Sessions can expire, so run the login command again if you see auth errors.

GLM: Set GLM_API_KEY to your Z.ai token (see GLM (Z.ai)).

Kimi: Install Claude Code and set KIMI_API_KEY to your Kimi API key (see Kimi).

Google: Run agy once to authenticate before using the antigravity backend. If you use the Gemini CLI backend instead, set GEMINI_API_KEY in the environment.

OpenCode: Install OpenCode and configure a provider and default model. Run opencode models and a direct opencode run --format json smoke test before using the backend.

Agent not found

Check that:

• Your agent file is in the .agents/ directory (or path specified by SUB_AGENTS_DIR)
• The file has .md or .txt extension
• The filename uses hyphens or underscores (no spaces)

CLI not found (exit code 127)

Install the required CLI:

• Codex: npm install -g @openai/codex
• Claude Code: curl -fsSL https://claude.ai/install.sh | bash
• Cursor CLI: curl https://cursor.com/install -fsS | bash
• Grok Build: curl -fsSL https://x.ai/cli/install.sh | bash
• Google Antigravity: curl -fsSL https://antigravity.google/cli/install.sh | bash
• OpenCode: brew install anomalyco/tap/opencode

If you use Gemini CLI, install it with npm install -g @google/gemini-cli.

Other execution errors

1. Verify the agent definition has valid run-agent frontmatter
2. Ensure your chosen CLI tool is installed and accessible
3. Check that --cwd is an absolute path to an existing directory

License

MIT