{"id":"306604d2-11b9-4f9b-81fe-b69c17c7e99d","shortId":"SFyWGz","kind":"skill","title":"subagents-management","tagline":"Create, edit, list, move, and delete subagents and skills for coding agents (Claude Code, Codex CLI, OpenCode). Manage AGENTS.md instructions, custom subagent definitions, and skill packages across user and project scopes.","description":"# Subagents & Skills Management\n\nManage subagents, skills, and instruction files for coding agents.\n\n- **Claude Code**: Subagents in `~/.claude/agents/` and `.claude/agents/`\n- **Codex CLI**: AGENTS.md instructions + custom subagents (TOML) in `~/.codex/agents/` + skills in `~/.codex/skills/` and `.agents/skills/`\n- **OpenCode**: `agent` blocks in `opencode.json` AND markdown agents in `~/.config/opencode/agents/` / `.opencode/agents/`; AGENTS.md for instructions\n\n**IMPORTANT**: After creating, modifying, or deleting subagents/skills, inform the user that they need to **restart the agent** for changes to take effect.\n\n**CRITICAL**: Before performing any deletion operation, you MUST use the `AskUserQuestion` tool to confirm with the user. Never delete a subagent without explicit user confirmation, even if using `--force` flag or direct `rm` commands.\n\n## Operations\n\n### List Subagents\n\n```bash\npython3 {SKILL_PATH}/scripts/list_subagents.py [--scope user|project|all] [--json]\n```\n\n### Create Subagent\n\nWrite a markdown file directly to the appropriate scope directory:\n\n**User scope:** `~/.claude/agents/{name}.md`\n**Project scope:** `.claude/agents/{name}.md`\n\nTemplate:\n```markdown\n---\nname: {name}\ndescription: {when Claude should use this subagent}\ntools: {comma-separated tools, or omit to inherit all}\ndisallowedTools: {optional denylist}\nmodel: {sonnet|opus|haiku|inherit, or full ID like claude-opus-4-7}\neffort: {low|medium|high|xhigh|max}\nmaxTurns: {optional turn cap}\npermissionMode: {default|acceptEdits|plan|auto|dontAsk|bypassPermissions}\nisolation: worktree   # optional, runs agent in a fresh git worktree\nbackground: true       # optional, run concurrently\ncolor: blue            # optional UI color\n---\n\n{System prompt - instructions for the subagent}\n```\n\nOr use the helper script:\n```bash\npython3 {SKILL_PATH}/scripts/create_subagent.py {name} \\\n  --description \"...\" \\\n  --prompt \"...\" \\\n  --scope {user|project} \\\n  --tools \"Read,Grep,Glob\" \\\n  --model sonnet\n```\n\n### Edit Subagent\n\n1. Find the file: `~/.claude/agents/{name}.md` or `.claude/agents/{name}.md`\n2. Edit the frontmatter and/or system prompt using Edit tool\n\n### Move Subagent\n\n```bash\npython3 {SKILL_PATH}/scripts/move_subagent.py {name} --to {user|project} [--overwrite]\n```\n\nOr manually:\n1. Read the source file\n2. Write to target directory\n3. Delete source file\n\n### Delete Subagent\n\n**⚠️ ALWAYS confirm with user before deleting.** Use `AskUserQuestion` to ask: \"Are you sure you want to delete the subagent '[name]'? This action cannot be undone.\"\n\n```bash\npython3 {SKILL_PATH}/scripts/delete_subagent.py {name} [--scope user|project] [--force]\n```\n\nOr delete directly (still requires user confirmation via AskUserQuestion first): `rm ~/.claude/agents/{name}.md` or `rm .claude/agents/{name}.md`\n\n## Codex CLI: AGENTS.md, Subagents & Skills\n\nCodex uses `AGENTS.md` (equivalent to `CLAUDE.md`) for project instructions, supports custom subagents via TOML files, and shares the SKILL.md format with Claude Code.\n\n### AGENTS.md\n\n```\n~/.codex/AGENTS.md                # Global instructions\n<project-root>/AGENTS.md          # Project instructions\n<project-root>/sub/AGENTS.md      # Subdirectory instructions (additive, root → leaf)\n<any-dir>/AGENTS.override.md      # Replaces AGENTS.md at that level\n```\n\nConfigure size limits and fallbacks via `project_doc_max_bytes` (default 32 KiB) and `project_doc_fallback_filenames` in `~/.codex/config.toml`.\n\n### Subagents (GA March 2026)\n\nCodex ships three built-in subagents — `default`, `explorer`, `worker` — and lets you define custom ones as TOML files in `~/.codex/agents/`:\n\n```toml\n# ~/.codex/agents/security-reviewer.toml\ndescription = \"Read-only security reviewer.\"\nmodel = \"gpt-5.5\"\nsandbox_mode = \"read-only\"\napproval_policy = \"never\"\n```\n\nRegister and tune orchestration in the main config:\n\n```toml\n[features]\nmulti_agent = true\n\n[agents]\nmax_threads = 6                   # Concurrent agent threads (default 6)\nmax_depth = 1                     # Max nesting; root = 0 (default 1)\n\n[agents.security-reviewer]\nconfig_file = \"~/.codex/agents/security-reviewer.toml\"\ndescription = \"Read-only security reviewer.\"\nnickname_candidates = [\"secrev\"]\n```\n\nCustom agents may include any standard config keys (`model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, `skills.config`). Subagents inherit the parent's interactive runtime overrides (e.g., `/approvals` changes, `--yolo`).\n\n### Skills\n\n```\n~/.codex/skills/<skill>/SKILL.md           # User skills (canonical default; $CODEX_HOME/skills)\n~/.agents/skills/<skill>/SKILL.md          # User skills (cross-tool alias path)\n<project-root>/.agents/skills/<skill>/SKILL.md  # Project skills\n```\n\nSkills use the same SKILL.md (YAML frontmatter) format as Claude Code and are cross-compatible across the Agent Skills standard. Stable in v0.124; the legacy `codex --enable skills` flag is still accepted but no longer required.\n\nSee [references/codex-agents.md](references/codex-agents.md) for the full Codex agents/skills reference.\n\n## OpenCode: agent blocks & AGENTS.md\n\nOpenCode (anomalyco/opencode v1.14.x) supports both JSON `agent` blocks in `opencode.json` and markdown files in `agents/`.\n\n### AGENTS.md (instructions)\n\n```\n~/.config/opencode/AGENTS.md           # Global personal instructions\n<project>/AGENTS.md                    # Project instructions (commit to git)\n```\n\nFalls back to `CLAUDE.md` and `~/.claude/CLAUDE.md` automatically when the OpenCode equivalents are missing.\n\n### Subagents\n\nTwo equivalent forms:\n\n**JSON in `opencode.json`:**\n```json\n{\n  \"agent\": {\n    \"reviewer\": {\n      \"mode\": \"subagent\",\n      \"description\": \"Reviews PRs for security issues\",\n      \"model\": \"anthropic/claude-opus-4-5\",\n      \"temperature\": 0.1,\n      \"prompt\": \"{file:./prompts/reviewer.md}\",\n      \"permission\": {\n        \"edit\": \"deny\",\n        \"bash\": { \"*\": \"deny\", \"rg *\": \"allow\" }\n      }\n    }\n  }\n}\n```\n\n**Markdown file** at `~/.config/opencode/agents/reviewer.md` or `<project>/.opencode/agents/reviewer.md`:\n```markdown\n---\nmode: subagent\ndescription: Reviews PRs for security issues\nmodel: anthropic/claude-opus-4-5\ntemperature: 0.1\npermission:\n  edit: deny\n  bash:\n    \"*\": deny\n    \"rg *\": allow\n---\n\nYou are a senior security reviewer...\n```\n\nOpenCode-specific fields not present in Claude Code subagents: `mode` (`primary`/`subagent`/`all`), `temperature`, `reasoningEffort`, `color`, granular `permission` glob rules, and full `provider/model-id` model strings.\n\n**CLI helpers:**\n```bash\nopencode agent create   # Interactive scaffolder\nopencode agent list     # List agents\n```\n\nSee [references/opencode-agents.md](references/opencode-agents.md) for the complete OpenCode agents/AGENTS.md reference.\n\n## Key Concepts (Claude Code)\n\n- **User scope** (`~/.claude/agents/`): Available in all projects\n- **Project scope** (`.claude/agents/`): Specific to current project, higher priority\n- Subagents reload on session restart or via `/agents` command\n- See [references/claude-subagents.md](references/claude-subagents.md) for Claude Code subagent schema\n\n## Common Patterns\n\n**Read-only reviewer:**\n```yaml\ntools: Read, Grep, Glob\nmodel: haiku\n```\n\n**Full-access helper:**\n```yaml\n# omit tools field to inherit all\nmodel: inherit\n```\n\n**Restricted with hooks:**\n```yaml\ntools: Bash\nhooks:\n  PreToolUse:\n    - matcher: \"Bash\"\n      hooks:\n        - type: command\n          command: \"./validate.sh\"\n```\n\n**Parallel worktree-isolated worker (2026):**\n```yaml\n---\nname: parallel-fixer\ndescription: Fix lint errors in isolation\nisolation: worktree\nbackground: true\nmodel: sonnet\nmaxTurns: 30\n---\n```\n\n**Tight allowlist + denylist (mind the ordering — `disallowedTools` is applied first):**\n```yaml\ntools: Read, Grep, Glob, Bash\ndisallowedTools: Write, Edit\nmodel: sonnet\ncolor: blue\n```","tags":["subagents","management","driven","development","codealive-ai","agent-safety","agent-skills","ai-coding","ai-driven-development","ai-safety","antigravity","bash"],"capabilities":["skill","source-codealive-ai","skill-subagents-management","topic-agent-safety","topic-agent-skills","topic-ai-coding","topic-ai-driven-development","topic-ai-safety","topic-antigravity","topic-bash","topic-claude-code","topic-codex-cli","topic-cursor","topic-developer-tools","topic-gemini-cli"],"categories":["ai-driven-development"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/CodeAlive-AI/ai-driven-development/subagents-management","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add CodeAlive-AI/ai-driven-development","source_repo":"https://github.com/CodeAlive-AI/ai-driven-development","install_from":"skills.sh"}},"qualityScore":"0.483","qualityRationale":"deterministic score 0.48 from registry signals: · indexed on github topic:agent-skills · 67 github stars · SKILL.md body (7,817 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-05-18T18:57:07.825Z","embedding":null,"createdAt":"2026-05-04T06:56:24.050Z","updatedAt":"2026-05-18T18:57:07.825Z","lastSeenAt":"2026-05-18T18:57:07.825Z","tsv":"'-5.5':485 '-7':210 '/.agents/skills':577,586 '/.claude/agents':51,165,282,375,798 '/.claude/claude.md':672 '/.codex/agents':62,474 '/.codex/agents.md':412 '/.codex/agents/security-reviewer.toml':476,529 '/.codex/config.toml':449 '/.codex/skills':65,569 '/.config/opencode/agents':77 '/.config/opencode/agents.md':657 '/.config/opencode/agents/reviewer.md':715 '/.opencode/agents/reviewer.md':717 '/agents':819 '/agents.md':415,661 '/agents.override.md':424 '/approvals':565 '/prompts/reviewer.md':704 '/scripts/create_subagent.py':263 '/scripts/delete_subagent.py':358 '/scripts/list_subagents.py':145 '/scripts/move_subagent.py':305 '/skill.md':570,578,587 '/sub/agents.md':418 '/validate.sh':869 '0':522 '0.1':701,730 '1':278,313,518,524 '2':289,318 '2026':453,875 '3':323 '30':894 '32':441 '4':209 '6':510,515 'accept':622 'acceptedit':223 'access':844 'across':30,606 'action':350 'addit':421 'agent':15,46,69,75,98,232,505,507,512,540,608,637,646,654,688,774,779,782 'agents.md':22,56,79,385,390,411,426,639,655 'agents.security':525 'agents/agents.md':790 'agents/skills':67,634 'alia':584 'allow':711,737 'allowlist':896 'alway':329 'and/or':293 'anomalyco/opencode':641 'anthropic/claude-opus-4-5':699,728 'appli':903 'appropri':160 'approv':491 'ask':338 'askuserquest':114,336,372 'auto':225 'automat':673 'avail':799 'back':668 'background':238,889 'bash':141,259,301,354,708,734,772,860,864,910 'block':70,638,647 'blue':244,917 'built':458 'built-in':457 'bypasspermiss':227 'byte':439 'candid':537 'cannot':351 'canon':573 'cap':220 'chang':100,566 'claud':16,47,179,207,409,599,751,794,825 'claude-opus':206 'claude.md':393,670 'claude/agents':53,170,286,380,805 'cli':19,55,384,770 'code':14,17,45,48,410,600,752,795,826 'codex':18,54,383,388,454,575,616,633 'color':243,247,760,916 'comma':186 'comma-separ':185 'command':137,820,867,868 'commit':664 'common':829 'compat':605 'complet':788 'concept':793 'concurr':242,511 'config':501,527,545 'configur':430 'confirm':117,128,330,370 'creat':4,84,151,775 'critic':104 'cross':582,604 'cross-compat':603 'cross-tool':581 'current':808 'custom':24,58,398,468,539 'default':222,440,461,514,523,574 'defin':467 'definit':26 'delet':9,87,108,122,324,327,334,345,365 'deni':707,709,733,735 'denylist':196,897 'depth':517 'descript':177,265,477,530,692,721,881 'direct':135,157,366 'directori':162,322 'disallowedtool':194,901,911 'doc':437,445 'dontask':226 'e.g':564 'edit':5,276,290,297,706,732,913 'effect':103 'effort':211,550 'enabl':617 'equival':391,677,682 'error':884 'even':129 'explicit':126 'explor':462 'fall':667 'fallback':434,446 'featur':503 'field':747,849 'file':43,156,281,317,326,402,472,528,652,703,713 'filenam':447 'find':279 'first':373,904 'fix':882 'fixer':880 'flag':133,619 'forc':132,363 'form':683 'format':407,597 'fresh':235 'frontmatt':292,596 'full':203,632,766,843 'full-access':842 'ga':451 'git':236,666 'glob':273,763,839,909 'global':413,658 'gpt':484 'granular':761 'grep':272,838,908 'haiku':200,841 'helper':257,771,845 'high':214 'higher':810 'home/skills':576 'hook':857,861,865 'id':204 'import':82 'includ':542 'inform':89 'inherit':192,201,557,851,854 'instruct':23,42,57,81,250,396,414,417,420,656,660,663 'interact':561,776 'isol':228,873,886,887 'issu':697,726 'json':150,645,684,687 'key':546,792 'kib':442 'leaf':423 'legaci':615 'let':465 'level':429 'like':205 'limit':432 'lint':883 'list':6,139,780,781 'longer':625 'low':212 'main':500 'manag':3,21,37,38 'manual':312 'march':452 'markdown':74,155,174,651,712,718 'matcher':863 'max':216,438,508,516,519 'maxturn':217,893 'may':541 'mcp':553 'md':167,172,284,288,377,382 'medium':213 'mind':898 'miss':679 'mode':487,552,690,719,754 'model':197,274,483,547,548,698,727,768,840,853,891,914 'modifi':85 'move':7,299 'multi':504 'must':111 'name':166,171,175,176,264,283,287,306,348,359,376,381,877 'need':94 'nest':520 'never':121,493 'nicknam':536 'omit':190,847 'one':469 'opencod':20,68,636,640,676,745,773,778,789 'opencode-specif':744 'opencode.json':72,649,686 'opencode/agents':78 'oper':109,138 'option':195,218,230,240,245 'opus':199,208 'orchestr':497 'order':900 'overrid':563 'overwrit':310 'packag':29 'parallel':870,879 'parallel-fix':878 'parent':559 'path':144,262,304,357,585 'pattern':830 'perform':106 'permiss':705,731,762 'permissionmod':221 'person':659 'plan':224 'polici':492 'present':749 'pretoolus':862 'primari':755 'prioriti':811 'project':33,148,168,269,309,362,395,416,436,444,588,662,802,803,809 'prompt':249,266,295,702 'provider/model-id':767 'prs':694,723 'python3':142,260,302,355 'read':271,314,479,489,532,832,837,907 'read-on':478,488,531,831 'reason':549 'reasoningeffort':759 'refer':635,791 'references/claude-subagents.md':822,823 'references/codex-agents.md':628,629 'references/opencode-agents.md':784,785 'regist':494 'reload':813 'replac':425 'requir':368,626 'restart':96,816 'restrict':855 'review':482,526,535,689,693,722,743,834 'rg':710,736 'rm':136,374,379 'root':422,521 'rule':764 'run':231,241 'runtim':562 'sandbox':486,551 'scaffold':777 'schema':828 'scope':34,146,161,164,169,267,360,797,804 'script':258 'secrev':538 'secur':481,534,696,725,742 'see':627,783,821 'senior':741 'separ':187 'server':554 'session':815 'share':404 'ship':455 'size':431 'skill':12,28,36,40,63,143,261,303,356,387,568,572,580,589,590,609,618 'skill-subagents-management' 'skill.md':406,594 'skills.config':555 'sonnet':198,275,892,915 'sourc':316,325 'source-codealive-ai' 'specif':746,806 'stabl':611 'standard':544,610 'still':367,621 'string':769 'subag':2,10,25,35,39,49,59,124,140,152,183,253,277,300,328,347,386,399,450,460,556,680,691,720,753,756,812,827 'subagents-manag':1 'subagents/skills':88 'subdirectori':419 'support':397,643 'sure':341 'system':248,294 'take':102 'target':321 'temperatur':700,729,758 'templat':173 'thread':509,513 'three':456 'tight':895 'toml':60,401,471,475,502 'tool':115,184,188,270,298,583,836,848,859,906 'topic-agent-safety' 'topic-agent-skills' 'topic-ai-coding' 'topic-ai-driven-development' 'topic-ai-safety' 'topic-antigravity' 'topic-bash' 'topic-claude-code' 'topic-codex-cli' 'topic-cursor' 'topic-developer-tools' 'topic-gemini-cli' 'true':239,506,890 'tune':496 'turn':219 'two':681 'type':866 'ui':246 'undon':353 'use':112,131,181,255,296,335,389,591 'user':31,91,120,127,147,163,268,308,332,361,369,571,579,796 'v0.124':613 'v1.14.x':642 'via':371,400,435,818 'want':343 'without':125 'worker':463,874 'worktre':229,237,872,888 'worktree-isol':871 'write':153,319,912 'xhigh':215 'yaml':595,835,846,858,876,905 'yolo':567","prices":[{"id":"ae80b10d-d4bd-4e1b-bbfd-e48576ecee27","listingId":"306604d2-11b9-4f9b-81fe-b69c17c7e99d","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"CodeAlive-AI","category":"ai-driven-development","install_from":"skills.sh"},"createdAt":"2026-05-04T06:56:24.050Z"}],"sources":[{"listingId":"306604d2-11b9-4f9b-81fe-b69c17c7e99d","source":"github","sourceId":"CodeAlive-AI/ai-driven-development/subagents-management","sourceUrl":"https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/subagents-management","isPrimary":false,"firstSeenAt":"2026-05-04T06:56:24.050Z","lastSeenAt":"2026-05-18T18:57:07.825Z"}],"details":{"listingId":"306604d2-11b9-4f9b-81fe-b69c17c7e99d","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"CodeAlive-AI","slug":"subagents-management","github":{"repo":"CodeAlive-AI/ai-driven-development","stars":67,"topics":["agent-safety","agent-skills","ai-coding","ai-driven-development","ai-safety","antigravity","bash","claude-code","codex-cli","cursor","developer-tools","gemini-cli","hooks","mcp","multi-agent","opencode","plugins","prompt-engineering","skills","subagents"],"license":"mit","html_url":"https://github.com/CodeAlive-AI/ai-driven-development","pushed_at":"2026-05-12T20:04:46Z","description":"Practices, protocols, and skills for AI-driven software development. 18 skills + 1 Bash safety hook for Claude Code, Codex CLI, OpenCode, Cursor, Gemini CLI, Antigravity, and any agent supporting the Agent Skills standard.","skill_md_sha":"4e2f6404a1e433131ff1e9f794a2366bf8c777ba","skill_md_path":"skills/subagents-management/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/subagents-management"},"layout":"multi","source":"github","category":"ai-driven-development","frontmatter":{"name":"subagents-management","description":"Create, edit, list, move, and delete subagents and skills for coding agents (Claude Code, Codex CLI, OpenCode). Manage AGENTS.md instructions, custom subagent definitions, and skill packages across user and project scopes."},"skills_sh_url":"https://skills.sh/CodeAlive-AI/ai-driven-development/subagents-management"},"updatedAt":"2026-05-18T18:57:07.825Z"}}