Sub-Agents Skills

English | 简体中文 | Русский | Deutsch | Español

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

Write an agent once in Markdown, then choose the backend that runs it. Send implementation, review, investigation, and verification work to different coding tools without duplicating 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 <client-skill-path>

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 Use It?

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.

run-agent	Backend	Executed CLI
codex	Codex	codex
claude	Claude Code	claude
cursor-agent	Cursor CLI	cursor-agent
glm	GLM (Z.ai)	claude with the Z.ai endpoint
kimi	Kimi	claude with the Kimi endpoint
grok	Grok Build	grok
antigravity	Google Antigravity	agy
gemini	Gemini CLI (compatibility)	gemini
opencode	OpenCode	opencode
command-code	Command Code	command-code

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

Frontmatter reference

Frontmatter Options

Field	Values	Description
run-agent	codex, claude, cursor-agent, glm, kimi, grok, antigravity, gemini, opencode, command-code	Which backend executes this agent
model	Backend-specific model name (optional)	Model passed to the selected CLI; omit to use its configured default
effort	Backend/model-specific value (optional)	Reasoning-effort override; omit to use the backend/model defau