sub-agents

Name: sub-agents
Author: shinpr

65stars8forks

How to install sub-agents?

shinpr/sub-agents-skills/sub-agents

$npx -y skills add shinpr/sub-agents-skills --skill sub-agents

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Sub-Agents - External CLI AI Task Delegation
2
3	Spawns external CLI AIs (codex, claude, cursor-agent, glm, grok, gemini, opencode) as isolated sub-agents with dedicated context.
4
5	Workflow: discover available definitions, select one from the user request, execute it, and handle the JSON response.
6
7	## Resources
8
9	- [run_subagent.py](scripts/run_subagent.py) - Main execution script
10	- [codex.md](references/codex.md) - Read before first execution from Codex; covers permissions and timeout
11
12	Script Path: Use absolute path `{SKILL_DIR}/scripts/run_subagent.py` where `{SKILL_DIR}` is the directory containing this SKILL.md file.
13
14	## Interpreting User Requests
15
16	Extract parameters from user's natural language request:
17
18	\| Parameter \| Source \|
19	\|-----------\|--------\|
20	\| `--agent` \| Agent name from the user request or workflow selection \|
21	\| `--prompt` \| Task instruction part (excluding agent specification) \|
22	\| `--cwd` \| Current working directory (absolute path) \|
23	\| `--cli` \| Backend override explicitly requested by the user; otherwise omit \|
24	\| `--timeout` \| Timeout explicitly requested by the user, converted to milliseconds; otherwise omit (default: 600000) \|
25
26	Example:
27	"Run code-reviewer on src/"
28	→ `--agent code-reviewer --prompt "Review src/" --cwd $(pwd)`
29
30	## Important: Permission and Timeout
31
32	This script executes external CLIs that require elevated permissions.
33
34	Before first execution:
35	1. Request elevated permissions via your CLI's tool parameters
36	2. Set tool timeout to match `--timeout` argument (default: 600000ms)
37
38	For Codex CLI (most common permission issues): See [references/codex.md](references/codex.md) for exact JSON parameter format.
39
40	## Workflow
41
42	### Step 1: List Available Agents
43
44	Always list agents first to discover available definitions:
45
46	```bash
47	{SKILL_DIR}/scripts/run_subagent.py --list
48	```
49
50	Output:
51	```json
52	{"agents": [{"name": "code-reviewer", "description": "Reviews code..."}], "agents_dir": "/path/.agents"}
53	```
54
55	When the user provides an agent name, select it if it appears in the result. If
56	it is absent, report the available definitions and wait for a selection. When
57	the result is empty, provide the Agent Definition Format below and wait for the
58	user to add a definition.
59
60	When the user leaves the agent selection open:
61
62	\| Available agents \| Action \|
63	\|------------------\|--------\|
64	\| 0 \| Report that no definitions are available, provide the Agent Definition Format below, and wait \|
65	\| 1 \| Select it \|
66	\| 2+ \| Show names and descriptions, then ask the user to select one \|
67
68	### Step 2: Execute Agent
69
70	```bash
71	{SKILL_DIR}/scripts/run_subagent.py \
72	--agent <name> \
73	--prompt "<task>" \
74	--cwd <absolute-path>
75	```
76
77	Append `--cli <backend>` when the user specifies a backend. Append
78	`--timeout <milliseconds>` when the user specifies a timeout.
79
80	### Step 3: Handle Response
81
82	Parse JSON output and check `status` field:
83
84	```json
85	{"result": "...", "exit_code": 0, "status": "success", "cli": "claude"}
86	```
87
88	By status:
89
90	\| status \| Meaning \| Action \|
91	\|--------\|---------\|--------\|
92	\| `success` \| Task completed \| Use `result` directly \|
93	\| `partial` \| Timeout but has output \| Review partial `result`, may need retry \|
94	\| `error` \| Execution failed \| Check `error` and `exit_code`; retry after satisfying the reported requirement \|
95
96	For configuration or credential errors, retry after the required external
97	configuration has changed.
98
99	By exit_code (when status is `error`):
100
101	\| exit_code \| Meaning \| Resolution \|
102	\|-----------\|---------\|------------\|
103	\| 0 \| Success \| - \|
104	\| 124 \| Timeout \| Increase `--timeout` or simplify task \|
105	\| 127 \| CLI not found \| Install required CLI (claude, codex, etc.) \|
106	\| 1 \| General error \| Check `error` field in response \|
107
108	## Agent Definition Location
109
110	\| Priority \| Source \| Path \|
111	\|----------\|--------\|------\|
112	\| 1 \| Environment variable \| `$SUB_AGENTS_DIR` \|
113	\| 2 \| Default \| `{cwd}/.agents/` \|
114
115	To customize: `export SUB_AGENTS_DIR=/custom/path`
116
117	## Agent Definition Format
118
119	Place `.md` files in `.agents/` directory:
120
121	```markdown
122	---
123	run-agent: claude
124	model: sonnet
125	permission: safe-edit
126	---
127
128	# Agent Name
129
130	Brief description of agent's purpose.
131
132	## Task
133	What this agent does.
134
135	## Output Format
136	How results should be structured.
137	```
138
139	`run-agent` supplies the backend; an explicit `--cli` argument overrides it.
140
141	Frontmatter fields:
142
143	\| Field \| Values \| Description \|
144	\|-------\|--------\|-------------\|
145	\| `run-agent` \| `codex`, `claude`, `cursor-agent`, `glm`, `grok`, `gemini`, `opencode` \| Which CLI executes this agent \|
146	\| `model` \| Backend-specific model name (optional) \| Model passed to the selected CLI; omit to use its configured default \|
147	\| `effort` \| Backend/model-specific reasoning level or OpenCode variant (optional) \| Advanced: forwarded as an opaque value. Confirm s

People who liked this also viewed

6 picks

Type

paperclip-create-agentCreate new agents in Paperclip with governance-aware hiring. Use when you need to inspect adapter configuration options, compare existing agent configs, draft a new agent prompt/config, and submit a hSkillsJul 2026157k5
subagent-driven-developmentUse when executing implementation plans with independent tasks in the current sessionSkillsJul 2026154k259k
dispatching-parallel-agentsUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesSkillsJul 2026143k259k
browser-act-skill-forgeForges reusable Skill packages (SKILL.md + scripts) from website exploration via browser-act — no re-exploration later. Use when: user wants a reusable Skill for any website, needs to understand a sitSkillsJul 202685k4.6k
wizardGenerate an interactive bash wizard that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening URLs, capturing values, confirming each stSkillsJul 202675k182k
wonda-cliUsing the Wonda CLI to generate images, videos, music, and audio from the terminal — plus LinkedIn, Reddit, and X/Twitter research and automationSkillsJul 202666k137

sub-agents

65stars8forks

View on GitHub

How to install sub-agents?

shinpr/sub-agents-skills/sub-agents

$npx -y skills add shinpr/sub-agents-skills --skill sub-agents

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Sub-Agents - External CLI AI Task Delegation
2
3	Spawns external CLI AIs (codex, claude, cursor-agent, glm, grok, gemini, opencode) as isolated sub-agents with dedicated context.
4
5	Workflow: discover available definitions, select one from the user request, execute it, and handle the JSON response.
6
7	## Resources
8
9	- [run_subagent.py](scripts/run_subagent.py) - Main execution script
10	- [codex.md](references/codex.md) - Read before first execution from Codex; covers permissions and timeout
11
12	Script Path: Use absolute path `{SKILL_DIR}/scripts/run_subagent.py` where `{SKILL_DIR}` is the directory containing this SKILL.md file.
13
14	## Interpreting User Requests
15
16	Extract parameters from user's natural language request:
17
18	\| Parameter \| Source \|
19	\|-----------\|--------\|
20	\| `--agent` \| Agent name from the user request or workflow selection \|
21	\| `--prompt` \| Task instruction part (excluding agent specification) \|
22	\| `--cwd` \| Current working directory (absolute path) \|
23	\| `--cli` \| Backend override explicitly requested by the user; otherwise omit \|
24	\| `--timeout` \| Timeout explicitly requested by the user, converted to milliseconds; otherwise omit (default: 600000) \|
25
26	Example:
27	"Run code-reviewer on src/"
28	→ `--agent code-reviewer --prompt "Review src/" --cwd $(pwd)`
29
30	## Important: Permission and Timeout
31
32	This script executes external CLIs that require elevated permissions.
33
34	Before first execution:
35	1. Request elevated permissions via your CLI's tool parameters
36	2. Set tool timeout to match `--timeout` argument (default: 600000ms)
37
38	For Codex CLI (most common permission issues): See [references/codex.md](references/codex.md) for exact JSON parameter format.
39
40	## Workflow
41
42	### Step 1: List Available Agents
43
44	Always list agents first to discover available definitions:
45
46	```bash
47	{SKILL_DIR}/scripts/run_subagent.py --list
48	```
49
50	Output:
51	```json
52	{"agents": [{"name": "code-reviewer", "description": "Reviews code..."}], "agents_dir": "/path/.agents"}
53	```
54
55	When the user provides an agent name, select it if it appears in the result. If
56	it is absent, report the available definitions and wait for a selection. When
57	the result is empty, provide the Agent Definition Format below and wait for the
58	user to add a definition.
59
60	When the user leaves the agent selection open:
61
62	\| Available agents \| Action \|
63	\|------------------\|--------\|
64	\| 0 \| Report that no definitions are available, provide the Agent Definition Format below, and wait \|
65	\| 1 \| Select it \|
66	\| 2+ \| Show names and descriptions, then ask the user to select one \|
67
68	### Step 2: Execute Agent
69
70	```bash
71	{SKILL_DIR}/scripts/run_subagent.py \
72	--agent <name> \
73	--prompt "<task>" \
74	--cwd <absolute-path>
75	```
76
77	Append `--cli <backend>` when the user specifies a backend. Append
78	`--timeout <milliseconds>` when the user specifies a timeout.
79
80	### Step 3: Handle Response
81
82	Parse JSON output and check `status` field:
83
84	```json
85	{"result": "...", "exit_code": 0, "status": "success", "cli": "claude"}
86	```
87
88	By status:
89
90	\| status \| Meaning \| Action \|
91	\|--------\|---------\|--------\|
92	\| `success` \| Task completed \| Use `result` directly \|
93	\| `partial` \| Timeout but has output \| Review partial `result`, may need retry \|
94	\| `error` \| Execution failed \| Check `error` and `exit_code`; retry after satisfying the reported requirement \|
95
96	For configuration or credential errors, retry after the required external
97	configuration has changed.
98
99	By exit_code (when status is `error`):
100
101	\| exit_code \| Meaning \| Resolution \|
102	\|-----------\|---------\|------------\|
103	\| 0 \| Success \| - \|
104	\| 124 \| Timeout \| Increase `--timeout` or simplify task \|
105	\| 127 \| CLI not found \| Install required CLI (claude, codex, etc.) \|
106	\| 1 \| General error \| Check `error` field in response \|
107
108	## Agent Definition Location
109
110	\| Priority \| Source \| Path \|
111	\|----------\|--------\|------\|
112	\| 1 \| Environment variable \| `$SUB_AGENTS_DIR` \|
113	\| 2 \| Default \| `{cwd}/.agents/` \|
114
115	To customize: `export SUB_AGENTS_DIR=/custom/path`
116
117	## Agent Definition Format
118
119	Place `.md` files in `.agents/` directory:
120
121	```markdown
122	---
123	run-agent: claude
124	model: sonnet
125	permission: safe-edit
126	---
127
128	# Agent Name
129
130	Brief description of agent's purpose.
131
132	## Task
133	What this agent does.
134
135	## Output Format
136	How results should be structured.
137	```
138
139	`run-agent` supplies the backend; an explicit `--cli` argument overrides it.
140
141	Frontmatter fields:
142
143	\| Field \| Values \| Description \|
144	\|-------\|--------\|-------------\|
145	\| `run-agent` \| `codex`, `claude`, `cursor-agent`, `glm`, `grok`, `gemini`, `opencode` \| Which CLI executes this agent \|
146	\| `model` \| Backend-specific model name (optional) \| Model passed to the selected CLI; omit to use its configured default \|
147	\| `effort` \| Backend/model-specific reasoning level or OpenCode variant (optional) \| Advanced: forwarded as an opaque value. Confirm s

People who liked this also viewed

6 picks

Type