login
ZhenHuangLab

collaborating-with-claude-code

by @ZhenHuangLab in Development
21
0
# Install this skill:
npx skills add ZhenHuangLab/collaborating-with-claude-code

Or install specific skill: npx add-skill https://github.com/ZhenHuangLab/collaborating-with-claude-code

# Description

Delegate code implementation/review/debugging/alternatives to Claude Code via a JSON bridge script. Multi-turn via SESSION_ID.

# SKILL.md

name: collaborating-with-claude-code
description: "Delegate code implementation/review/debugging/alternatives to Claude Code via a JSON bridge script. Multi-turn via SESSION_ID."
metadata:
short-description: Use Claude Code as a collaborator

Collaborating with Claude Code

Use this skill for second opinions, code review, test design, or code implementations/alternatives. The bridge runs claude (Claude Code) non-interactively ("print" mode) and returns JSON.

The script is located at ~/.codex/skills/collaborating-with-claude-code/scripts/claude_code_bridge.py.

Timing

Claude Code often needs 1–2+ minutes per task.
- Prefer running the bridge directly (no &); increase --timeout-s as needed (default: 1800s).
- Do NOT redirect stdout to a file (e.g. > /tmp/out.json).

Context

  • Do NOT read the script unless you are modifying it;
  • Before running the script, ALWAYS use python <script_loc> --help to get the usage instructions.

Usage

  • please always require claude code to fully understand the codebase before responding or making any changes.
  • Put collaborating-with-claude-code terminal commands in the background terminal.
  • Always review claude code's responses (or changes it makes) and make sure they are correct, constructive and complete.
  • When claude code asks clarifying questions in a multi-turn session, always respond to its questions in that session based on current situation.

Default

  • full access (--full-access): use only in trusted repos/directories.
  • extended thinking ON (can disable via --no-extended-thinking).
  • step mode ON (can disable via --step-mode off).

Output format

The bridge prints JSON:

{"success": true, "SESSION_ID": "abc123", "agent_messages": "…Claude output…", "all_messages": []}
  • Guided coding: "Implement the code for [feature] following these specific steps/constraints."
  • Second opinion: "Propose an alternative approach and tradeoffs."
  • Code review: "Find bugs, race conditions, security issues; propose fixes."
  • Test design: "Write a test plan + edge cases; include example test code."
  • Diff review: "Review this patch; point out regressions and missing cases."

# README.md

collaborating-with-claude-code

中文 | English

Codex CLI 的一个 skill ：通过一个 JSON bridge 脚本，把“代码审查 / 调试 / 方案对比”等任务委托给 Anthropic Claude Code CLI（默认模型：claude-opus-4-5-20251101），并以结构化 JSON 结果返回，便于在多模型协作中使用。

本仓库的核心入口是 SKILL.md（Codex skill 定义）以及 scripts/claude_code_bridge.py（桥接脚本）。

Features

本skill相对于其他类似skill/协作模式，具有如下重要优势：

  1. 使用SOTA的context engineering技术，遵循渐进式披露 (progressive disclosure) 的原则，让codex只需要一次tool call就可以掌握该skill script的使用方法，第二次tool call即可正确调用，无需再搜索/读取该脚本；
  2. 兼容各类“在extended thinking开启后会对message结构进行严格校验的” Anthropic-compatible proxy.
    • 对于某些Anthropic-compatible proxy API, 在thinking启用后，包含工具调用链路的assistant消息，需要满足“assistant message 必须以 thinking/redacted_thinking 开头，然后才是 tool_use，再配套 tool_result ……”这类规则。而在print模式下使用claude code时，如果产生上述tool call 链路，thinking部分信息会在claude code侧被filtered掉，assistant message会以tool_use开头，从而导致router返回400 Error. 而这一问题在claude code交互界面一般不会出现。
    • 针对这一问题，skill中的 bridge script 采取了“把一次长的agentic loop拆成很多次短的loop”的策略：
      • 每次仅允许 claude code 做一次 agentic turn （最多仅一次tool call就调用停止）
      • 然后bridge script 会用相同的session_id自动发送很短的继续指令，让它进行下一步
    • 通过这种方法，可以最大限度地兼容通过各类Anthropic-compatible proxy API运行的claude code.

安装到 ~/.codex/skills/

1) 选择一个安装目录（如果不存在就创建）：

mkdir -p ~/.codex/skills

2) 克隆本仓库到 skills 目录下（目录名就是 skill 名）：

cd ~/.codex/skills
git clone https://github.com/ZhenHuangLab/collaborating-with-claude-code.git collaborating-with-claude-code

3) 验证文件结构（至少应包含 SKILL.md 和 scripts/）：

ls -la ~/.codex/skills/collaborating-with-claude-code

4) 确认claude_code_bridge.py脚本路径：

默认为~/.codex/skills/collaborating-with-claude-code/scripts/claude_code_bridge.py. 如果有变动，请在 SKILL.md中修改.

测试表明，在 SKILL.md 中直接显式声明script的正确路径，会让codex执行bridge script变得更加高效。

完成后，Codex CLI 在加载本地 skills 时就能发现它；在对话中提到 collaborating-with-claude-code（或 $collaborating-with-claude-code，或自然语言的类似要求）即可触发使用。

依赖

  • Python 3（用于运行 bridge 脚本）。
  • 已安装并可用的 Claude Code CLI（确保 claude --version 可运行）。
  • Claude Code 已完成认证（例如通过环境变量 ANTHROPIC_API_KEY，或你本机 Claude Code 所需的其它认证方式）。

注意：该 skill 默认以 full access 方式运行 Claude Code（非交互、绕过确认），只建议在你信任的目录/仓库中使用。

手动运行（不通过 Codex CLI）

python <script_loc> --cd "/path/to/repo" --PROMPT "Review the auth flow for bypasses; propose fixes as a unified diff."

只读审查（避免改文件/跑命令）：

python <script_loc> --no-full-access --cd "/path/to/repo" --PROMPT "Review the auth flow and list issues (no code changes)."

更完整的参数说明与多轮会话用法见 SKILL.md。

兼容性

已经在codex v0.87, claude code v2.1.11 and v2.1.12 测试通过.

License

MIT License，详见 LICENSE。

# Related Skills

facebook
feature-flags @facebook

Use when feature flag tests fail, flags need updating, understanding @gate pragmas, debugging...

★ 242,571
facebook
fix @facebook

Use when you have lint errors, formatting issues, or before committing code to ensure it passes CI.

★ 242,571
facebook
flags @facebook

Use when you need to check feature flag states, compare channels, or debug why a feature behaves...

★ 242,571

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.