Claude Code Agent Development
anthropics/claude-plugins-official
Explains how to write agents for Claude Code plugins: the markdown file with YAML frontmatter, trigger descriptions, model and color settings, and system prompt design.
Invoke this skill when the user asks to use subagents or when a substantial, self-contained task can run independently in the background.
Install Subagents
$ npx skills add openpi-dev/openpi --skill subagents -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install openpi-dev/openpi subagents --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/openpi-dev/openpi.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/subagents .claude/skills/subagents && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "subagents" agent skill from https://github.com/openpi-dev/openpi/tree/main/skills/subagents into .claude/skills/subagents/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "subagents", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/openpi-dev/openpi/tree/main/skills/subagentsType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add openpi-dev/openpi --skill subagents -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install openpi-dev/openpi subagents --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/openpi-dev/openpi.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/subagents .agents/skills/subagents && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "subagents" agent skill from https://github.com/openpi-dev/openpi/tree/main/skills/subagents into .agents/skills/subagents/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "subagents", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add openpi-dev/openpi --skill subagents -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install openpi-dev/openpi subagents --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/openpi-dev/openpi.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/subagents .cursor/skills/subagents && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "subagents" agent skill from https://github.com/openpi-dev/openpi/tree/main/skills/subagents into .cursor/skills/subagents/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "subagents", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/openpi-dev/openpi.git --path skills/subagents--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add openpi-dev/openpi --skill subagents -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install openpi-dev/openpi subagents --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/openpi-dev/openpi.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/subagents .gemini/skills/subagents && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "subagents" agent skill from https://github.com/openpi-dev/openpi/tree/main/skills/subagents into .gemini/skills/subagents/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "subagents", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install openpi-dev/openpi subagentsInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add openpi-dev/openpi --skill subagents -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/openpi-dev/openpi.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/subagents .github/skills/subagents && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "subagents" agent skill from https://github.com/openpi-dev/openpi/tree/main/skills/subagents into .github/skills/subagents/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "subagents", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add openpi-dev/openpi --skill subagents -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install openpi-dev/openpi subagents --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/openpi-dev/openpi.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/subagents .opencode/skills/subagents && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "subagents" agent skill from https://github.com/openpi-dev/openpi/tree/main/skills/subagents into .opencode/skills/subagents/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "subagents", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
subagents- GitHub stars
- 169
- Token cost
- ~821 tokens
- SKILL.md length
- 456 words
- Files
- 2
- Skills in repo
- 3
- Repo updated
- First seen
- Licence
- MIT
At a glance
Invoke this skill when the user asks to use subagents or when a substantial, self-contained task can run independently in the background.
- Asks to use subagents
- Calls git
- Self-contained task can run independently in the background
What it does
Subagents is an agent skill from openpi-dev/openpi. Invoke this skill when the user asks to use subagents or when a substantial, self-contained task can run independently in the background.
Its SKILL.md is about 820 tokens, which your agent loads only when the skill is triggered. The skill folder holds 1 other file (for example `REFERENCE.md`).
It sits in Agent Workflows, covering Subagents. The repository describes itself as: The setup I use for pi. Changes a ton, don't recommend hard copying it, just a taste of what's possible with it. The licence is MIT.
When your agent uses it
- Asks to use subagents
- Self-contained task can run independently in the background
Example prompts
- “/subagents”
What it can do on your machine
Read from SKILL.md and the folder at commit 3cb2ecf. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
git
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Subagents loads about 821 tokens when it runs. Until then it costs about 37 tokens; SKILL.md has 456 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check: notes
The automated check noted patterns worth knowing about, such as sudo or a known installer.
- NoteMentions a .env fileSKILL.md:22
itignored files such as build output or `.env`. A successful committed child leaves a branch for the parent to merge. An
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from openpi-dev/openpi at commit 3cb2ecf, republished under its MIT licence (© openpi-dev). 456 words, ~821 tokens.
Download SKILL.mdSave it as
.claude/skills/subagents/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.- name
- subagents
- description
- Invoke this skill when the user asks to use subagents or when a substantial, self-contained task can run independently in the background.
Subagents
The tool definitions are canonical for parameters, limits, model syntax, isolation, and lifecycle commands. This skill governs delegation decisions only.
- Delegate substantial independent work, not a lookup or edit the parent can do directly.
- Give the child a standalone prompt with paths, constraints, relevant context, and the expected report; it cannot see the parent conversation or ask the user.
- Inherit the parent model by default. When choosing the child's reasoning effort, honor an explicit user requirement first; otherwise use the selected role's relative guidance and the task's difficulty, choosing from levels supported by the resolved child model.
- Prefer a matching agent type when one exists; built-ins inherit active parent tools, while an explicit custom tool list is enforced as a narrowing restriction. Model precedence is explicit spawn override, selected type-file model, configured built-in role model, then parent model. Reasoning precedence is explicit spawn override, selected type default, then parent effort. Types live in
~/.pi/agent/agents/*.mdand, for trusted projects,.pi/agents/*.md; see Agent types. - Isolate concurrent writers in worktrees according to the
subagent_spawnschema so they cannot overwrite one checkout or git index. While Plan Mode is active, use only read-only exploration types (or no type); worktree isolation and types narrowed by Plan Mode are rejected. - After spawning, continue useful parent work. In an interactive session, if none remains, tell the user the child is still running and end the turn; automatic result delivery will re-invoke the parent when it settles. Do not block merely because the next step depends on the result or because there is nothing else to do. Use
subagent_waitonly when the user explicitly asks to keep the current response open for the result, or when non-interactive automation must return it in the same invocation. - Use optional
output_schemawhen downstream work needs a machine-validated result rather than prose. The child then receives one terminatingstructured_outputtool, and the run fails if it finishes without submitting a matching value. Keep schemas small and task-specific; the validated JSON is delivered to the parent and preserved in a private content-addressed artifact. Omit the option for ordinary text reports.
Show full SKILL.md (108 more words)Show less
Worktree isolation
Concurrent writers without isolation share the same checkout and Git index, so edits and git add operations can overwrite each other. Set isolation: "worktree" and tell every writing child to commit.
The worktree is branched from HEAD, requires a Git repository, and starts clean without gitignored files such as build output or .env. A successful committed child leaves a branch for the parent to merge. An empty branch can be deleted; dirty, untracked, ignored, detached, timed-out, or uninspectable work is preserved instead of being destroyed. Direct subagents retain their checkout for later subagent_send review and only reclaim it on Session retirement after a bounded empty-work proof.
© openpi-dev, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 1 other file in skills/subagents of openpi-dev/openpi.
- SKILL.md
- REFERENCE.md
Open the folder on GitHubat commit 3cb2ecf
Compare with similar skills
Subagents next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Subagents this skillopenpi-dev/openpi | 169 | — | ~821 | Automated safety check: Notes | MIT | |
| Claude Code Agent Developmentanthropics/claude-plugins-official | 37k | 8 repos | ~2.8k | Automated safety check: Pass | Apache-2.0 | |
| Subagent Driven DevelopmentAsvarox/allkaraoke | 261 | 37 repos | ~1.2k | Automated safety check: Pass | None | |
| Dispatching Parallel Agentsultralisp/ultralisp | 258 | 40 repos | ~1.5k | Automated safety check: Pass | None | |
| Paseo Advisor Second Opiniongetpaseo/paseo | 20k | 1 repos | ~756 | Automated safety check: Pass | Custom licence | |
| Task Observerrebelytics/one-skill-to-rule-them-all | 3.2k | 1 repos | ~12k | Automated safety check: Pass | CC-BY-4.0 |
Similar skills
- Official
Subagent Driven Development
Asvarox/allkaraoke
A skill your agent uses when executing implementation plans with independent tasks in the current session
Dispatching Parallel Agents
ultralisp/ultralisp
A skill your agent uses when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
Paseo Advisor Second Opinion
getpaseo/paseo
Launches one separate agent through Paseo to give a second opinion on the current task, with a self-contained briefing and no permission to edit files.
Task Observer
rebelytics/one-skill-to-rule-them-all
Monitors task execution for skill improvement opportunities.
O2 Review Loop
openobserve/openobserve
Splits a change into planner, coder and independent reviewer roles: you confirm a spec, a subagent implements it, and a separate reviewer checks each round's local WIP commit.
More from openpi-dev/openpi
Workflows
openpi-dev/openpi
Orchestrates multi-agent work with OpenPI's inline JavaScript Workflow DSL.
Background Terminals
openpi-dev/openpi
Run and manage long-lived shell commands in background terminals.
Related
Categories
Questions about Subagents
What does Subagents do?
Invoke this skill when the user asks to use subagents or when a substantial, self-contained task can run independently in the background. Subagents is an agent skill from openpi-dev/openpi. Invoke this skill when the user asks to use subagents or when a substantial, self-contained task can run independently in the background.
When should I use Subagents?
Subagents fits situations like: asks to use subagents; self-contained task can run independently in the background.
How do I install Subagents in Claude Code?
Run `npx skills add openpi-dev/openpi --skill subagents -a claude-code`. Or copy the skill folder (skills/subagents in openpi-dev/openpi) into .claude/skills/subagents in your project. Claude Code loads it when a task matches its description.
How do I install Subagents in Codex?
Run `npx skills add openpi-dev/openpi --skill subagents -a codex`. Or copy the skill folder (skills/subagents in openpi-dev/openpi) into .agents/skills/subagents in your project. Codex loads it when a task matches its description.
Can I use Subagents in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add openpi-dev/openpi --skill subagents -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/subagents, .gemini/skills/subagents, .github/skills/subagents and .opencode/skills/subagents in your project.
What does Subagents need to run?
Going by SKILL.md and its folder, Subagents needs the command-line tools its instructions call (git).
Does Subagents access the network?
SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.
Is Subagents safe to install?
Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.
What licence does Subagents use?
Subagents is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Subagents use?
About 821 tokens (SKILL.md is roughly 3.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Subagents?
Skills that share tags, products or a category with Subagents: Claude Code Agent Development (anthropics/claude-plugins-official, 37k stars), Subagent Driven Development (Asvarox/allkaraoke, 261 stars), Dispatching Parallel Agents (ultralisp/ultralisp, 258 stars) and Paseo Advisor Second Opinion (getpaseo/paseo, 20k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Subagents?
openpi-dev (a GitHub organization) maintains it in openpi-dev/openpi, which has 169 GitHub stars. The repository holds 3 skills in this directory. The repository was last updated on October 5, 2026.
Source: openpi-dev/openpi on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.