{"id":"2f8e7126-c830-4db6-9ed6-8b8a0b7ebe3a","shortId":"7W4gKQ","kind":"skill","title":"sub-agents","tagline":"Run agent definitions as sub-agents. Use when the user names an agent or sub-agent to run, references an agent definition, or delegates a task to an agent.","description":"# Sub-Agents - External CLI AI Task Delegation\n\nSpawns external CLI AIs (claude, cursor-agent, codex, gemini) as isolated sub-agents with dedicated context.\n\n## Resources\n\n- **[run_subagent.py](scripts/run_subagent.py)** - Main execution script\n- **[codex.md](references/codex.md)** - Codex-specific setup (permissions, timeout)\n\n**Script Path**: Use absolute path `{SKILL_DIR}/scripts/run_subagent.py` where `{SKILL_DIR}` is the directory containing this SKILL.md file.\n\n## CLI-Specific Notes\n\nCheck the corresponding reference for your environment:\n- **Codex**: Read [references/codex.md](references/codex.md) BEFORE first execution\n\n## Interpreting User Requests\n\nExtract parameters from user's natural language request:\n\n| Parameter | Source |\n|-----------|--------|\n| --agent | Agent name from user request (see selection rules below) |\n| --prompt | Task instruction part (excluding agent specification) |\n| --cwd | Current working directory (absolute path) |\n\n**Agent Selection Rules** (when user doesn't specify agent name):\n1. Run `--list` to get available agents\n2. **0 agents**: Inform user no agents available, show setup instructions (see [Agent Definition Format](#agent-definition-format))\n3. **1 agent**: Auto-select without asking\n4. **2+ agents**: Show list with descriptions, ask user to choose\n\n**Example**:\n\"Run code-reviewer on src/\"\n→ `--agent code-reviewer --prompt \"Review src/\" --cwd $(pwd)`\n\n## Important: Permission and Timeout\n\nThis script executes external CLIs that require elevated permissions.\n\n**Before first execution:**\n1. Request elevated permissions via your CLI's tool parameters\n2. Set tool timeout to match `--timeout` argument (default: 600000ms)\n\n**For Codex CLI** (most common permission issues): See [references/codex.md](references/codex.md) for exact JSON parameter format.\n\n## Workflow\n\n### Step 0: Read CLI-Specific Setup (if applicable)\n\nIf you are running on Codex, read [references/codex.md](references/codex.md) first.\n\n### Step 1: List Available Agents\n\n**Always list agents first** to discover available definitions:\n\n```bash\nscripts/run_subagent.py --list\n```\n\nOutput:\n```json\n{\"agents\": [{\"name\": \"code-reviewer\", \"description\": \"Reviews code...\"}], \"agents_dir\": \"/path/.agents\"}\n```\n\n**If agents list is empty**:\n1. Create `{cwd}/.agents/` directory\n2. Add agent definition file (see [Agent Definition Format](#agent-definition-format))\n3. Re-run `--list` to verify\n\n### Step 2: Execute Agent\n\n```bash\nscripts/run_subagent.py \\\n  --agent <name> \\\n  --prompt \"<task>\" \\\n  --cwd <absolute-path>\n```\n\n### Step 3: Handle Response\n\nParse JSON output and check `status` field:\n\n```json\n{\"result\": \"...\", \"exit_code\": 0, \"status\": \"success\", \"cli\": \"claude\"}\n```\n\n**By status:**\n\n| status | Meaning | Action |\n|--------|---------|--------|\n| `success` | Task completed | Use `result` directly |\n| `partial` | Timeout but has output | Review partial `result`, may need retry |\n| `error` | Execution failed | Check `error` field and `exit_code`, fix and retry |\n\n**By exit_code** (when status is `error`):\n\n| exit_code | Meaning | Resolution |\n|-----------|---------|------------|\n| 0 | Success | - |\n| 124 | Timeout | Increase `--timeout` or simplify task |\n| 127 | CLI not found | Install required CLI (claude, codex, etc.) |\n| 1 | General error | Check `error` field in response |\n\n## Parameters\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `--list` | - | List available agents (no other params needed) |\n| `--agent` | Yes* | Agent definition name from --list |\n| `--prompt` | Yes* | Task description to delegate |\n| `--cwd` | Yes* | Working directory (absolute path) |\n| `--timeout` | No | Timeout ms (default: 600000) |\n| `--cli` | No | Force CLI: `claude`, `cursor-agent`, `codex`, `gemini` |\n\n*Required when not using --list\n\n## Agent Definition Location\n\n| Priority | Source | Path |\n|----------|--------|------|\n| 1 | Environment variable | `$SUB_AGENTS_DIR` |\n| 2 | Default | `{cwd}/.agents/` |\n\nTo customize: `export SUB_AGENTS_DIR=/custom/path`\n\n## Agent Definition Format\n\nPlace `.md` files in `.agents/` directory:\n\n```markdown\n---\nrun-agent: claude\n---\n\n# Agent Name\n\nBrief description of agent's purpose.\n\n## Task\nWhat this agent does.\n\n## Output Format\nHow results should be structured.\n```\n\n**Critical**: The `run-agent` frontmatter determines which CLI executes the agent.\n\n## CLI Selection Priority\n\n1. `--cli` argument (explicit override)\n2. Agent definition `run-agent` frontmatter\n3. Auto-detect caller environment\n4. Default: `codex`\n\n## Common Mistakes\n\n| Mistake | Result | Fix |\n|---------|--------|-----|\n| Skip `--list` before execution | Agent not found error | Always run `--list` first |\n| Use relative path for `--cwd` | Validation fails | Use absolute path |\n| Ignore `status` field in response | Undetected errors | Always check `status` before using `result` |\n| Very long prompts | May exceed CLI limits | Break into smaller tasks |","tags":["sub","agents","skills","shinpr","agent-skills","ai-agents","claude-code","codex","cursor","developer-tools","gemini-cli","llm-orchestration"],"capabilities":["skill","source-shinpr","skill-sub-agents","topic-agent-skills","topic-ai-agents","topic-claude-code","topic-codex","topic-cursor","topic-developer-tools","topic-gemini-cli","topic-llm-orchestration","topic-multi-llm","topic-skills","topic-sub-agents"],"categories":["sub-agents-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/shinpr/sub-agents-skills/sub-agents","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add shinpr/sub-agents-skills","source_repo":"https://github.com/shinpr/sub-agents-skills","install_from":"skills.sh"}},"qualityScore":"0.461","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 22 github stars · SKILL.md body (4,954 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-23T07:01:01.921Z","embedding":null,"createdAt":"2026-04-18T23:06:09.668Z","updatedAt":"2026-04-23T07:01:01.921Z","lastSeenAt":"2026-04-23T07:01:01.921Z","tsv":"'/.agents':326,516 '/custom/path':523 '/path/.agents':317 '/scripts/run_subagent.py':82 '0':165,271,372,422 '1':157,184,234,290,323,441,507,573 '124':424 '127':431 '2':164,192,244,328,349,513,578 '3':183,341,358,585 '4':191,591 '600000':485 '600000ms':253 'absolut':78,145,478,619 'action':381 'add':329 'agent':3,5,10,17,21,26,34,37,50,57,124,125,139,147,155,163,166,170,176,180,185,193,209,293,296,307,315,319,330,334,338,351,354,456,461,463,493,501,511,521,524,531,536,538,543,549,562,569,579,583,603 'agent-definition-format':179,337 'ai':40,46 'alway':294,607,628 'applic':278 'argument':251,575 'ask':190,198 'auto':187,587 'auto-detect':586 'auto-select':186 'avail':162,171,292,300,455 'bash':302,352 'break':641 'brief':540 'caller':589 'check':97,365,402,444,629 'choos':201 'claud':47,376,438,490,537 'cli':39,45,94,240,256,274,375,432,437,486,489,566,570,574,639 'cli-specif':93,273 'clis':226 'code':205,211,310,314,371,407,413,419 'code-review':204,210,309 'codex':51,70,104,255,284,439,494,593 'codex-specif':69 'codex.md':67 'common':258,594 'complet':384 'contain':89 'context':60 'correspond':99 'creat':324 'critic':558 'current':142 'cursor':49,492 'cursor-ag':48,491 'custom':518 'cwd':141,216,325,356,474,515,615 'dedic':59 'default':252,484,514,592 'definit':6,27,177,181,301,331,335,339,464,502,525,580 'deleg':29,42,473 'descript':197,312,452,471,541 'detect':588 'determin':564 'dir':81,85,316,512,522 'direct':387 'directori':88,144,327,477,532 'discov':299 'doesn':152 'elev':229,236 'empti':322 'environ':103,508,590 'error':399,403,417,443,445,606,627 'etc':440 'exact':265 'exampl':202 'exceed':638 'exclud':138 'execut':65,110,224,233,350,400,567,602 'exit':370,406,412,418 'explicit':576 'export':519 'extern':38,44,225 'extract':114 'fail':401,617 'field':367,404,446,623 'file':92,332,529 'first':109,232,288,297,610 'fix':408,598 'forc':488 'format':178,182,268,336,340,526,552 'found':434,605 'frontmatt':563,584 'gemini':52,495 'general':442 'get':161 'handl':359 'ignor':621 'import':218 'increas':426 'inform':167 'instal':435 'instruct':136,174 'interpret':111 'isol':54 'issu':260 'json':266,306,362,368 'languag':120 'limit':640 'list':159,195,291,295,304,320,345,453,454,467,500,600,609 'locat':503 'long':635 'main':64 'markdown':533 'match':249 'may':396,637 'md':528 'mean':380,420 'mistak':595,596 'ms':483 'name':15,126,156,308,465,539 'natur':119 'need':397,460 'note':96 'output':305,363,392,551 'overrid':577 'param':459 'paramet':115,122,243,267,449,450 'pars':361 'part':137 'partial':388,394 'path':76,79,146,479,506,613,620 'permiss':73,219,230,237,259 'place':527 'prioriti':504,572 'prompt':134,213,355,468,636 'purpos':545 'pwd':217 're':343 're-run':342 'read':105,272,285 'refer':24,100 'references/codex.md':68,106,107,262,263,286,287 'relat':612 'request':113,121,129,235 'requir':228,436,451,496 'resolut':421 'resourc':61 'respons':360,448,625 'result':369,386,395,554,597,633 'retri':398,410 'review':206,212,214,311,313,393 'rule':132,149 'run':4,23,158,203,282,344,535,561,582,608 'run-ag':534,560,581 'run_subagent.py':62 'script':66,75,223 'scripts/run_subagent.py':63,303,353 'see':130,175,261,333 'select':131,148,188,571 'set':245 'setup':72,173,276 'show':172,194 'simplifi':429 'skill':80,84 'skill-sub-agents' 'skill.md':91 'skip':599 'smaller':643 'sourc':123,505 'source-shinpr' 'spawn':43 'specif':71,95,140,275 'specifi':154 'src':208,215 'status':366,373,378,379,415,622,630 'step':270,289,348,357 'structur':557 'sub':2,9,20,36,56,510,520 'sub-ag':1,8,19,35,55 'success':374,382,423 'task':31,41,135,383,430,470,546,644 'timeout':74,221,247,250,389,425,427,480,482 'tool':242,246 'topic-agent-skills' 'topic-ai-agents' 'topic-claude-code' 'topic-codex' 'topic-cursor' 'topic-developer-tools' 'topic-gemini-cli' 'topic-llm-orchestration' 'topic-multi-llm' 'topic-skills' 'topic-sub-agents' 'undetect':626 'use':11,77,385,499,611,618,632 'user':14,112,117,128,151,168,199 'valid':616 'variabl':509 'verifi':347 'via':238 'without':189 'work':143,476 'workflow':269 'yes':462,469,475","prices":[{"id":"b9a64449-feec-4465-a647-8573a75c3d92","listingId":"2f8e7126-c830-4db6-9ed6-8b8a0b7ebe3a","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"shinpr","category":"sub-agents-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T23:06:09.668Z"}],"sources":[{"listingId":"2f8e7126-c830-4db6-9ed6-8b8a0b7ebe3a","source":"github","sourceId":"shinpr/sub-agents-skills/sub-agents","sourceUrl":"https://github.com/shinpr/sub-agents-skills/tree/main/skills/sub-agents","isPrimary":false,"firstSeenAt":"2026-04-18T23:06:09.668Z","lastSeenAt":"2026-04-23T07:01:01.921Z"}],"details":{"listingId":"2f8e7126-c830-4db6-9ed6-8b8a0b7ebe3a","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"shinpr","slug":"sub-agents","github":{"repo":"shinpr/sub-agents-skills","stars":22,"topics":["agent-skills","ai-agents","claude-code","codex","cursor","developer-tools","gemini-cli","llm-orchestration","multi-llm","skills","sub-agents"],"license":"mit","html_url":"https://github.com/shinpr/sub-agents-skills","pushed_at":"2026-04-04T07:34:15Z","description":"Cross-LLM sub-agent orchestration as an Agent Skills. Route tasks to Codex, Claude Code, Cursor, or Gemini from any compatible tool.","skill_md_sha":"74fd8b29a3c2440cbd4c5364c573d8a9d2987a84","skill_md_path":"skills/sub-agents/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/shinpr/sub-agents-skills/tree/main/skills/sub-agents"},"layout":"multi","source":"github","category":"sub-agents-skills","frontmatter":{"name":"sub-agents","description":"Run agent definitions as sub-agents. Use when the user names an agent or sub-agent to run, references an agent definition, or delegates a task to an agent."},"skills_sh_url":"https://skills.sh/shinpr/sub-agents-skills/sub-agents"},"updatedAt":"2026-04-23T07:01:01.921Z"}}