子代理技能

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:

```bash

Backend Setup

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

<a id="glm-zai"></a> <details> <summary>GLM (Z.ai)</summary>

The glm backend runs the Claude Code binary against GLM's Anthropic-compatible endpoint. Install Claude Code, then set your Z.ai token:

export GLM_API_KEY=<your-z.ai-token>

The runner sends the key through the child environment and points Claude Code at https://api.z.ai/api/anthropic.

</details>

<a id="kimi"></a> <details> <summary>Kimi</summary>

The kimi backend runs the Claude Code binary against Kimi's coding endpoint. Install Claude Code, then set your Kimi API key:

export KIMI_API_KEY=<your-kimi-api-key>

The runner sends the key through the child environment and points Claude Code at https://api.kimi.com/coding/.

Provider-specific keys take priority, so multiple backends can remain configured at the same time:

export GLM_API_KEY=<your-z.ai-token>
export KIMI_API_KEY=<your-kimi-api-key>
export CURSOR_API_KEY=<your-cursor-token> # optional when cursor-agent is logged in

</details>

<a id="opencode"></a> <details> <summary>OpenCode</summary>

The opencode backend uses the model selected in the agent definition. If model is omitted, it uses OpenCode's configured default. Through OpenCode, an agent can run on supported providers, OpenAI-compatible APIs, gateways, or local models.

Configure OpenCode in ~/.config/opencode/opencode.json or the project's opencode.json, then use provider/model syntax when selecting a model:

Quick Start

Requirements: Python 3.9+ and at least one supported backend installed.

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.

Frontmatter Options

run-agent is required unless --cli explicitly overrides it for one run.

effort is forwarded unchanged to the selected backend. Accepted values depend on the backend and model, so check the provider documentation before setting it. Invalid combinations fail at runtime. Cursor and Gemini do not support this field.

Permission levels:

• read-only: investigation/review mode that prevents direct edits where supported; shell behavior depends on the backend and this mode is not a security boundary (codex -s read-only / claude --permission-mode plan / cursor --mode plan --sandbox enabled / grok --sandbox read-only / antigravity --mode plan --sandbox / gemini --approval-mode plan / OpenCode permission rules / Command Code --permission-mode plan)
• safe-edit: default non-interactive edit mode (codex -s workspace-write + approval_policy=never / claude --permission-mode acceptEdits / cursor --trust --sandbox enabled / grok --sandbox workspace / antigravity --mode accept-edits --sandbox / gemini --approval-mode auto_edit / OpenCode permission rules / Command Code --yolo --permission-mode auto-accept)
• yolo: bypass all approvals and sandboxing; use it only for tasks and environments you trust.

Sub-agents have no stdin, so the runner uses non-interactive backend modes. The isolation guarantees depend on the selected CLI; permission flags are not equivalent across backends. For Cursor, the sandbox confines supported shell commands, while --mode plan supplies the read-only constraint.

</details>

<details> <summary>Agent authoring guidelines</summary>

Optional Agent Sections

Add these sections when the agent needs them:

• Scope boundaries: Explicitly state what's out of scope
• Prohibited actions: List common mistakes the agent should avoid
• Output format: Define structured output when needed

</details>

<details> <summary>Complete agent example</summary>

Each .md or .txt file in your .agents/ folder becomes an agent. The filename becomes the agent name (e.g., bug-investigator.md → "bug-investigator").

bug-investigator.md

Configuration Reference

<details> <summary>Agent location and backend selection</summary>

CLI Selection Priority

1. --cli argument (explicit one-run override)
2. Agent definition run-agent frontmatter
3. Error if neither is specified

--cli always overrides the agent definition's run-agent; omit it for normal runs.

</details>

<details> <summary>Direct runner CLI parameters</summary>

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 - Command Code: npm install -g command-code

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

VS Code / Copilot (project-scoped)

curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target .github/skills

Troubleshooting