From subagent-cli
将任意 Agent CLI(ClaudeCode、Codex CLI、OpenCode CLI、CodeBuddy CLI 等)封装为当前主 Agent 的可复用 subAgent Tool。 当用户提到"把 XX CLI 作为 subAgent"、"封装 XX CLI"、"用 XX CLI 执行任务"、"并行调用 XX CLI"时触发此技能。 也适用于用户想让多个 Agent CLI 协作完成任务的场景。
How this skill is triggered — by the user, by Claude, or both
Slash command
/subagent-cli:subagent-cliThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
将任意 Agent CLI 封装为当前主 Agent 的可复用 Tool,支持并行派发任务。
将任意 Agent CLI 封装为当前主 Agent 的可复用 Tool,支持并行派发任务。
整个封装过程分为 7 步,其中前 3 步是必须通过的门禁。
用户触发技能时,先判断是否明确指定了目标 CLI。
判断规则:用户消息中提到了具体的 CLI 名称(如"用 Claude Code 作为 subAgent"、"封装 Codex CLI")则视为明确指定,跳过此门禁。
未明确指定时,弹出选择框:
请选择要封装为 subAgent 的 Agent CLI:
- Claude Code — Anthropic 官方,Node.js,浏览器登录或 API Key
- Codex CLI — OpenAI 官方,Node.js,ChatGPT 登录或 API Key
- Gemini CLI — Google 官方,Node.js,Google 账号登录(免费额度)
- Aider — Python,支持 100+ 语言,多模型
- Crush (原 OpenCode) — Go,Charmbracelet,多 LLM
- CodeBuddy — 自研/内部工具
- 其他 — 输入自定义 CLI 名称
用户选择后,记录目标 CLI 名称,进入下一个门禁。
当检测到当前系统为 Windows 时,需确认用户已安装 Git Bash。
检测方式:检查 MSYSTEM 或 GIT_BASH 环境变量,或检查 uname 输出是否包含 MINGW / MSYS。
uname -s 2>/dev/null | grep -qiE 'MINGW|MSYS' && echo "Git Bash" || echo "Not Git Bash"
检测到当前系统为 Windows。subagent-cli 的脚本依赖 Bash 环境,请先安装 Git for Windows: https://git-scm.com/download/win
安装完成后,请在 Git Bash 中重新运行此技能。
用户确认已安装后重新检测。未确认则终止。
在做任何事之前,先确认目标 CLI 是否可用。
<cli_name> --version
目标 CLI
<cli_name>未安装或不在 PATH 中。 是否需要安装?安装后请确保已完成登录认证。
用户确认已安装并登录后,重新检测。未确认则终止。
| CLI | 安装命令 | 登录方式 |
|---|---|---|
| Claude Code | npm install -g @anthropic-ai/claude-code | 首次运行引导登录,或设 ANTHROPIC_API_KEY |
| Codex CLI | npm install -g @openai/codex | ChatGPT 账号登录,或设 OPENAI_API_KEY |
| Gemini CLI | npm install -g @google/gemini-cli | Google 账号浏览器登录(免费 60 请求/分钟) |
| Crush (原 OpenCode) | npm install -g @charmland/crush | 设对应 LLM 提供商的 API Key |
| Aider | pip install aider-chat | 设对应模型的 API Key |
| CodeBuddy | 按项目文档安装 | 按项目文档配置 |
详细安装方法和参数说明见 references/cli-patterns.md。
subAgent 需要读写文件权限才能正常执行任务。在开始封装前,询问用户:
为了让 subAgent 能执行读写操作,需要放开以下权限:
- 读取文件(Read)
- 写入文件(Write/Edit)
- 执行命令(Bash,按需)
是否同意?
用户确认后,在封装脚本中通过 --permission-mode 或 --allowedTools 配置权限。
先检查 scripts/<cli_name>-ctl.sh 是否已存在:
--help 侦察并编写脚本读取 --help 输出,识别:
--output-format json、--print 等--permission-mode、--allowedTools、--disallowedTools、-y 等--task-id、--session-id、--max-turns 等Agent 型 CLI 需要特别注意行为控制(禁用不需要的工具,防止自主行为偏离预期)。
<cli_name> --help 2>&1
如果 scripts/<cli_name>-ctl.sh 已存在,跳过此步。否则根据第 3 步侦察结果生成脚本:
创建一个 <cli_name>-ctl.sh wrapper 脚本,统一接口:
<cli_name>-ctl.sh run --task-id <id> [--bg] [--allowed-tools <tools>] [--permission-mode <mode>] [-- <prompt>]
<cli_name>-ctl.sh status --task-id <id> | --all
<cli_name>-ctl.sh result --task-id <id>
<cli_name>-ctl.sh cancel --task-id <id>
--bg 支持后台执行,前台执行自动等待--allowed-tools 和 --permission-mode 透传给底层 CLIresult 命令从原始输出中提取最终结果(支持 JSON 数组和 JSONL 格式)python -c 处理 UTF-8,避免 GBK 编码问题将封装脚本注册为主 Agent 的可调用 Tool。
subAgent 不经过 LLM,直接调用 wrapper 脚本:
import subprocess, json
def <cli_name>_run(prompt, task_id, allowed_tools=None, permission_mode=None):
args = ["bash", "<cli_name>-ctl.sh", "run", "--task-id", task_id]
if allowed_tools:
args.extend(["--allowed-tools", allowed_tools])
if permission_mode:
args.extend(["--permission-mode", permission_mode])
args.extend(["--", prompt])
result = subprocess.run(args, capture_output=True, timeout=300)
return json.loads(result.stdout.decode("utf-8"))
subAgent 有自己的 LLM,能自主决策:
def <cli_name>_agent(task):
# 调用 Anthropic API,定义 tools,跑 tool_use 循环
# 参考 anthropic SDK 文档
pass
--allowed-tools 配置当用户要求验证 subAgent 编排能力时,优先使用临时目录和只读/最小权限任务,避免修改真实仓库文件。
先确认所有目标 CLI 都能完成非交互最小对话,而不只是 --version 可用:
codex exec --sandbox read-only --skip-git-repo-check "Reply exactly: CODEX_OK"
claude -p --output-format json --permission-mode acceptEdits -- "Reply exactly: CLAUDE_OK"
Not logged in · Please run /login,说明 Claude 侧未完成登录,不能继续验证 Claude 调 Codex。claude 不在 PATH,用 zsh -lic 'command -v claude' 定位真实路径,或显式把 nvm 的 Node bin 目录加到测试命令的 PATH。node/npm,但 Codex App 提供 bundled Node,可临时把 bundled Node 加入 PATH,不要污染系统全局安装。python,但系统只有 python3,先显式记录环境缺口;测试时可临时把 Python 3.10+ 软链到临时 PATH 中。codex exec 时给进程关闭 stdin(例如命令末尾加 < /dev/null),避免 Codex 进入 Reading additional input from stdin... 后等待输入而不执行后续命令。验证 Codex CLI 与 Claude Code 双向调用时,使用固定字符串和临时目录:
--permission-mode bypassPermissions 在临时目录执行 codex exec --sandbox read-only --skip-git-repo-check "Reply exactly: CODEX_FROM_CLAUDE_OK",再检查结果文件。验证并行能力时至少同时启动 3 个只读子任务,并检查每个任务都返回唯一标记:
codex exec --json -o /tmp/a.result.txt --sandbox read-only --skip-git-repo-check "Reply exactly: A_OK" &
codex exec --json -o /tmp/b.result.txt --sandbox read-only --skip-git-repo-check "Reply exactly: B_OK" &
codex exec --json -o /tmp/c.result.txt --sandbox read-only --skip-git-repo-check "Reply exactly: C_OK" &
wait
通过标准:
如果直接调用 CLI 成功,但 *-ctl.sh wrapper 失败,先检查 wrapper 自身:
check_auth_errors 不应让普通 warning 触发认证失败;优先匹配明确的错误字段或清晰的认证失败短语。completed,必须记录真实退出码。set -e 下要显式捕获非 0 退出码,否则会停留在 running 状态。status 和 result 必须读取同一份任务状态文件;在 Unix/macOS 上不要把 TASK_DIR 拼成 "$TASK_DIR_WIN\\$id.json",Windows 路径转换只应在 Git Bash/Windows 环境下启用。完成真实验证后,可以用 SkillOpt-Sleep 提炼会话经验,但不要盲目 adopt:
export SKILLOPT_SLEEP_REPO=/path/to/SkillOpt
export PATH="/path/to/python-3.10-plus/bin:$PATH"
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" dry-run --project "$(pwd)"
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" run --project "$(pwd)" --backend codex
bash "$SKILLOPT_SLEEP_REPO/plugins/run-sleep.sh" status --project "$(pwd)"
采纳规则:
accepted=true 且 edits 非空时,才考虑 adopt。accepted=false 或 edits=[] 时,不要强行应用;改为人工审查测试结果,把可复用门禁补充到本技能。| 场景 | 推荐模式 | 原因 |
|---|---|---|
| 生成文本/代码 | 纯 Tool | 不需要 LLM 决策,直接执行 |
| 需要多步推理 | Agent 模式 | subAgent 需要自主判断中间步骤 |
| 严格控制行为 | 纯 Tool + 禁用工具 | 防止 Agent 自主行为偏离 |
| 并行批量任务 | 纯 Tool | 无额外 API 开销,速度更快 |
max_workers 控制,避免资源耗尽auth、unauthorized、401、403、timeout、connection refused、Reconnecting、credentials 等关键词时,立即停止任务,抛出错误并询问用户检查 API Key 或登录状态,不要重试或静默忽略scripts/ 目录下包含可直接使用的封装脚本,各脚本头部有完整用法说明:
scripts/check_cli.sh — 检测任意 Agent CLI 是否可用scripts/claude-ctl.sh — Claude Code CLI wrapper(run/status/result/cancel/cleanup)scripts/codex-ctl.sh — Codex CLI wrapper(run/status/result/cancel/cleanup)scripts/opencode-ctl.sh — OpenCode CLI wrapper(run/status/result/cancel/cleanup)scripts/codebuddy-ctl.sh — CodeBuddy CLI wrapper(run/status/result/cancel/cleanup)所有 *-ctl.sh 脚本内置 check_auth_errors:执行后自动检测 auth/unauthorized/401/403/Reconnecting/timeout waiting 等关键词,发现即终止并返回错误 JSON,提示用户检查 API Key 或登录状态。
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub silicon-based-lin/subagent-cli --plugin subagent-cli