From 15604b53c554be638b654fd49506829793e38904 Mon Sep 17 00:00:00 2001 From: empty Date: Sun, 11 Jan 2026 17:22:33 +0800 Subject: [PATCH] Fix codex-collab skill structure to comply with Claude Code skill specification Changes: - Rename skill.md to SKILL.md (uppercase required) - Add YAML frontmatter with name and description - Reorganize templates/ and examples/ into references/ - Remove extra documentation files (README.md, QUICK_REF.md) - Follow progressive disclosure pattern: keep SKILL.md lean The skill now complies with the official Claude Code skill format. Co-Authored-By: Claude --- codex-collab/QUICK_REF.md | 161 ------------- codex-collab/README.md | 223 ------------------ .../{templates => references}/code-review.md | 0 .../complete-session.md | 0 .../debug-analysis.md | 0 .../design-proposal.md | 0 .../requirement-analysis.md | 0 codex-collab/skill.md | 198 +++++----------- 8 files changed, 65 insertions(+), 517 deletions(-) delete mode 100644 codex-collab/QUICK_REF.md delete mode 100644 codex-collab/README.md rename codex-collab/{templates => references}/code-review.md (100%) rename codex-collab/{examples => references}/complete-session.md (100%) rename codex-collab/{templates => references}/debug-analysis.md (100%) rename codex-collab/{templates => references}/design-proposal.md (100%) rename codex-collab/{templates => references}/requirement-analysis.md (100%) diff --git a/codex-collab/QUICK_REF.md b/codex-collab/QUICK_REF.md deleted file mode 100644 index 36a5eff..0000000 --- a/codex-collab/QUICK_REF.md +++ /dev/null @@ -1,161 +0,0 @@ -# Codex Collaboration Skill - 快速参考卡 - -## 快速决策流程 - -``` - ┌─────────────────┐ - │ 用户需求 │ - └────────┬────────┘ - │ - ▼ - ┌─────────────────┐ - │ 是查找/定位？ │ - └────────┬────────┘ - 是/ │ \否 - / │ \ - ▼ │ ▼ - ┌──────────┐ │ ┌──────────────┐ - │ 调 Codex │ │ │ 评估复杂度 │ - │ 搜索定位 │ │ └──────┬───────┘ - └──────────┘ │ │ - │ ┌─────┴─────┐ - │ ▼ ▼ - │ 简单 中等/复杂 - │ │ │ - │ ▼ ▼ - │ 直接执行 ┌─────────┐ - │ │ 调 Codex│ - │ │ 分析方案│ - │ └─────────┘ - │ -``` - -## 常用命令 - -### 1. 代码搜索/定位 -```python -codex( - PROMPT="搜索与【功能描述】相关的代码", - cd="/project", - sandbox="read-only" -) -``` - -### 2. 需求分析 -```python -codex( - PROMPT="分析需求：{用户需求}", - cd="/project", - sandbox="read-only" -) -# 保存 SESSION_ID -``` - -### 3. 继续讨论 -```python -codex( - PROMPT="关于你的方案，{疑问/讨论点}", - cd="/project", - SESSION_ID="上次的SESSION_ID", - sandbox="read-only" -) -``` - -### 4. 请求代码原型 -```python -codex( - PROMPT="提供代码原型（unified diff patch）：{功能说明}", - cd="/project", - SESSION_ID="上次的SESSION_ID", - sandbox="read-only" -) -``` - -### 5. 代码审查 -```python -codex( - PROMPT="审查代码：{改动说明}", - cd="/project", - SESSION_ID="之前的SESSION_ID" -) -``` - -## 参数速查表 - -| 参数 | 常用值 | 说明 | -|------|--------|------| -| `cd` | 项目路径 | **必选**，必须指向存在的目录 | -| `sandbox` | "read-only" | **推荐**，最安全 | -| `SESSION_ID` | 之前的ID | 多轮对话必传 | -| `return_all_messages` | True/False | 是否需要详细推理过程 | - -## 安全检查清单 - -调用 Codex 前检查： -- [ ] `cd` 参数是否正确 -- [ ] 是否需要使用 `SESSION_ID` 继续 -- [ ] `sandbox` 是否设置为 "read-only" -- [ ] 是否明确要求 unified diff patch - -调用 Codex 后检查： -- [ ] 是否保存了返回的 `SESSION_ID` -- [ ] `success` 字段是否为 `true` -- [ ] 是否需要验证 Codex 的建议 - -## 常见场景 - -| 场景 | 调用 Codex | Claude Code | -|------|-----------|-------------| -| 查找代码 | ✅ 搜索定位 | - | -| 理解代码 | ✅ 分析解释 | - | -| Bug定位 | ✅ 调试分析 | - | -| 需求分析 | ✅ 分析方案 | - | -| 功能设计 | ✅ 设计方案 | 讨论完善 | -| 代码实现 | ❌ 不用 | ✅ 编写代码 | -| 代码审查 | ✅ 审查代码 | 根据意见调整 | - -## 最佳实践 - -### DO ✅ -- 始终追踪 `SESSION_ID` -- 使用 `sandbox="read-only"` -- 保持批判性思维 -- 完成编码后立即审查 -- 明确要求 unified diff - -### DON'T ❌ -- 盲目接受建议 -- 让 Codex 直接改代码 -- 忘记保存 SESSION_ID -- 跳过审查环节 -- 使用 danger-full-access - -## 会话状态跟踪 - -```python -# 建议在会话开始时创建变量 -codex_session = { - "session_id": None, - "stage": "init", # init | analysis | design | review - "context": {} -} - -# 每次调用后更新 -def update_session(result): - codex_session["session_id"] = result.get("SESSION_ID") - # ... -``` - -## 错误处理 - -```python -result = codex(...) - -if not result.get("success"): - # 处理错误 - print(f"Error: {result.get('error')}") - # 可能的恢复策略： - # 1. 检查 cd 路径 - # 2. 检查 Codex 是否安装 - # 3. 尝试不传 SESSION_ID 重新开始 -``` diff --git a/codex-collab/README.md b/codex-collab/README.md deleted file mode 100644 index 8dbf58c..0000000 --- a/codex-collab/README.md +++ /dev/null @@ -1,223 +0,0 @@ -# Codex Collaboration Skill - -**智能协作框架 - 让 Claude Code 和 Codex CLI 高效协作** - -## 概述 - -Codex Collaboration Skill 是一个专为 Claude Code 设计的协作框架，封装了与 Codex CLI 进行高效、安全协作的最佳实践。通过 CodexMCP 协议，实现两个 AI 编程助手的优势互补。 - -### 核心价值 - -- **智能任务分类**：自动判断任务复杂度，选择最优协作策略 -- **标准化流程**：封装经过验证的协作模式 -- **会话管理**：简化多轮对话和上下文管理 -- **安全规范**：内置最佳实践和安全准则 - -## 快速开始 - -### 安装 - -1. 确保已安装 CodexMCP： -```bash -claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp -``` - -2. 将此 skill 添加到 Claude Code skills 目录： -```bash -# 默认 skills 目录：~/.claude/skills/ -cp -r codex-collaboration-skill ~/.claude/skills/ -``` - -### 基本使用 - -当用户需求涉及以下场景时，Claude Code 会自动启用此 skill： - -- 代码查找和定位 -- 需求分析和方案设计 -- 代码审查 -- Bug 诊断 -- 架构优化 - -## 工作流程 - -### 任务复杂度评估 - -``` -简单任务 → 直接执行 - ↓ -中等任务 → [Codex]查找定位 → [Codex]逻辑梳理 → [Codex]方案设计 - → [Claude]代码实现 → [Codex]代码审查 - ↓ -复杂任务 → [Codex]深度分析 → [Claude+Codex]并行设计审查 - → [Codex]多轮方案迭代 → [Claude]分阶段实现 → [Codex]严格审查 -``` - -### 关键原则 - -1. **批判性思维**：Codex 是协作伙伴，不是唯一真理来源 -2. **独立判断**：对所有建议保持审视 -3. **辩论求真**：通过讨论达成最优方案 -4. **安全第一**：默认使用 sandbox="read-only" -5. **会话管理**：始终追踪 SESSION_ID - -## 文件结构 - -``` -codex-collaboration-skill/ -├── skill.md # 核心技能文档 -├── README.md # 本文件 -├── templates/ # 工作流模板 -│ ├── code-review.md # 代码审查模板 -│ ├── requirement-analysis.md # 需求分析模板 -│ ├── design-proposal.md # 方案设计模板 -│ └── debug-analysis.md # 调试分析模板 -└── examples/ # 使用示例（待添加） -``` - -## 模板说明 - -### 1. Code Review Template -用于代码审查，包含： -- 正确性检查 -- 代码质量评估 -- 性能分析 -- 安全检查 -- 测试覆盖验证 -- 文档完整性 - -### 2. Requirement Analysis Template -用于需求分析，包含： -- 需求理解 -- 技术可行性评估 -- 影响范围分析 -- 实施方案建议 -- 风险识别 -- 测试策略 - -### 3. Design Proposal Template -用于方案设计，包含： -- 整体设计 -- 接口设计 -- 数据模型设计 -- 核心逻辑设计 -- 技术选型 -- 安全设计 -- 性能考虑 -- 实施计划 -- 测试策略 -- 部署和运维 - -### 4. Debug Analysis Template -用于调试分析，包含： -- 问题定位 -- 影响范围分析 -- 解决方案 -- 预防措施 -- 验证方法 - -## 使用示例 - -### 示例 1：代码审查 - -```python -# 完成编码后，调用代码审查模板 -codex( - PROMPT=code_review_template.format( - modified_files="- src/auth/login.py: 添加用户登录验证", - change_description="实现了基于JWT的用户认证", - requirement="实现用户登录功能" - ), - cd="/project", - SESSION_ID=previous_session -) -``` - -### 示例 2：需求分析 - -```python -# 新功能需求分析 -codex( - PROMPT=requirement_analysis_template.format( - user_requirement="实现实时通知系统", - context="SaaS平台，使用Python+FastAPI", - constraints="需要向后兼容" - ), - cd="/project", - sandbox="read-only" -) -``` - -### 示例 3：调试分析 - -```python -# Bug 定位和分析 -codex( - PROMPT=debug_analysis_template.format( - error_message="AssertionError: User should be authenticated", - reproduction_steps="1. 登录 2. 等待30分钟 3. 创建订单", - context="订单创建接口需要用户认证", - recent_changes="昨天修改了JWT解码逻辑" - ), - cd="/project", - sandbox="read-only" -) -``` - -## Codex Tool 参数 - -### 必选参数 -- `PROMPT` (str): 任务指令 -- `cd` (Path): 工作目录根路径 - -### 可选参数 -| 参数 | 类型 | 默认值 | 说明 | -|------|------|--------|------| -| `sandbox` | str | "read-only" | 沙箱策略 | -| `SESSION_ID` | UUID | None | 会话ID | -| `return_all_messages` | bool | False | 返回完整推理 | -| `model` | str | None | 指定模型 | - -### 返回值 -```json -{ - "success": true, - "SESSION_ID": "uuid-string", - "agent_messages": "Codex响应内容" -} -``` - -## 最佳实践 - -### DO - 推荐做法 - -- ✅ 使用 sandbox="read-only" 进行方案设计和审查 -- ✅ 要求 Codex 仅提供 unified diff patch -- ✅ 保持批判性思维，质疑不合理的建议 -- ✅ 使用 SESSION_ID 进行多轮对话 -- ✅ 完成编码后立即让 Codex 审查 - -### DON'T - 避免做法 - -- ❌ 盲目接受 Codex 的所有建议 -- ❌ 让 Codex 直接修改代码 -- ❌ 忽略 SESSION_ID 管理 -- ❌ 跳过代码审查环节 -- ❌ 使用 danger-full-access 除非绝对必要 - -## 相关资源 - -- [CodexMCP 项目](https://github.com/GuDaStudio/codexmcp) -- [Claude Code 文档](https://docs.claude.com/docs/claude-code) -- [Codex CLI 文档](https://developers.openai.com/codex) - -## 贡献 - -欢迎贡献改进建议和新的模板！ - -## 许可证 - -MIT License - ---- - -**Made with ❤️ for better AI-assisted programming** diff --git a/codex-collab/templates/code-review.md b/codex-collab/references/code-review.md similarity index 100% rename from codex-collab/templates/code-review.md rename to codex-collab/references/code-review.md diff --git a/codex-collab/examples/complete-session.md b/codex-collab/references/complete-session.md similarity index 100% rename from codex-collab/examples/complete-session.md rename to codex-collab/references/complete-session.md diff --git a/codex-collab/templates/debug-analysis.md b/codex-collab/references/debug-analysis.md similarity index 100% rename from codex-collab/templates/debug-analysis.md rename to codex-collab/references/debug-analysis.md diff --git a/codex-collab/templates/design-proposal.md b/codex-collab/references/design-proposal.md similarity index 100% rename from codex-collab/templates/design-proposal.md rename to codex-collab/references/design-proposal.md diff --git a/codex-collab/templates/requirement-analysis.md b/codex-collab/references/requirement-analysis.md similarity index 100% rename from codex-collab/templates/requirement-analysis.md rename to codex-collab/references/requirement-analysis.md diff --git a/codex-collab/skill.md b/codex-collab/skill.md index fd9c063..4475903 100644 --- a/codex-collab/skill.md +++ b/codex-collab/skill.md @@ -1,13 +1,30 @@ -# Codex Collaboration Skill +--- +name: codex-collab +description: Codex 协作框架 - 让 Claude Code 和 Codex CLI 高效协作。适用于代码查找定位、需求分析、方案设计、代码审查、Bug 诊断等场景。 +--- -## Description +# Codex 协作框架 -**Codex Collaboration Skill** 是一个专为 Claude Code 设计的协作框架，用于与 Codex CLI 进行高效、安全的智能协作。通过 CodexMCP 协议，实现两个 AI 编程助手的优势互补： +智能协作框架，通过 CodexMCP 协议实现 Claude Code 与 Codex CLI 的优势互补。 -- **Claude Code**: 擅长架构设计、需求分析、代码重构 -- **Codex**: 擅长代码生成、精确定位、细节优化 +## 核心原则 -## When to Use This Skill +**指导原则**： +- Codex 是协作伙伴，而非唯一真理来源 +- 必须有独立思考，对 Codex 的建议保持批判性审视 +- 通过辩论和讨论达成最优方案 + +**职责分工**： +- **Claude Code**：代码编写、文档编写、简单任务直接执行 +- **Codex**：代码查找定位、逻辑梳理、代码审查、方案设计、问题诊断 + +**关键规范**： +- 查找/搜索任务 → 必须调用 Codex +- 方案设计阶段 → 使用 `sandbox="read-only"` +- 代码实现 → Claude Code 基于方案重写生产级代码 +- 完成编码后 → 立即让 Codex 审查 + +## 何时使用 当用户需求涉及以下场景时，应主动使用此 skill： @@ -17,162 +34,77 @@ 4. **Bug 诊断**：分析错误原因、定位问题代码 5. **架构优化**：评估设计方案、提出改进建议 -## Task Complexity Assessment +## 任务复杂度评估 -在开始任务前，必须先进行复杂度评估： - -### Simple Tasks (直接执行) +### 简单任务（直接执行） 满足**所有**以下条件： -- ✅ 无生产影响（如文档、注释、简单查询） -- ✅ 无需新增基础设施或外部依赖 -- ✅ 不涉及多个子系统协调 +- 无生产影响（如文档、注释、简单查询） +- 无需新增基础设施或外部依赖 +- 不涉及多个子系统协调 -**示例**：查询数据、添加日志、修改文案、简单重命名 - -### Medium Tasks (Codex协作) +### 中等任务（Codex协作） 满足**至少一个**以下条件： -- 📊 有限生产影响（需要测试验证） -- 📊 需要小规模配置调整或库引入 -- 📊 需要理解模块间调用关系 +- 有限生产影响（需要测试验证） +- 需要小规模配置调整或库引入 +- 需要理解模块间调用关系 -**示例**：功能增强、Bug修复、接口调整、业务逻辑优化 - -### Complex Tasks (深度Codex协作) +### 复杂任务（深度Codex协作） 满足**至少两个**以下条件： -- 🔥 高生产影响（安全、性能、数据一致性） -- 🔥 架构变更、新基础设施、核心依赖升级 -- 🔥 需要多agent协调或跨团队对齐 +- 高生产影响（安全、性能、数据一致性） +- 架构变更、新基础设施、核心依赖升级 +- 需要多agent协调或跨团队对齐 -**示例**：新模块开发、架构重构、性能优化、安全加固 +## 工作流程 -## Workflow Templates - -### 简单任务工作流 ``` -用户需求 → 快速分析 → 直接实现 → 简单自检 → 完成 +简单任务：直接执行 + ↓ +中等任务：[Codex]查找定位 → [Codex]逻辑梳理 → [Codex]方案设计 + → [Claude]代码实现 → [Codex]代码审查 + ↓ +复杂任务：[Codex]深度分析 → [Claude+Codex]并行设计审查 + → [Codex]多轮方案迭代 → [Claude]分阶段实现 → [Codex]严格审查 ``` -### 中等任务工作流 -``` -用户需求 → [Codex]查找定位 → [Codex]逻辑梳理 - → [Codex]方案设计 → [Claude]代码实现 → [Codex]代码审查 → 完成 -``` +## Codex Tool 速查 -### 复杂任务工作流 -``` -用户需求 → [Codex]深度分析 → [Claude+Codex]并行设计审查 - → [Codex]多轮方案迭代 → [Claude]分阶段实现 → [Codex]严格审查 → 完成 -``` - -## Codex Tool Reference - -### Required Parameters +### 必选参数 - `PROMPT` (str): 任务指令 - `cd` (Path): 工作目录根路径 -### Optional Parameters -| 参数 | 类型 | 默认值 | 说明 | -|------|------|--------|------| -| `sandbox` | str | "read-only" | 沙箱策略：read-only / workspace-write / danger-full-access | -| `SESSION_ID` | UUID \| None | None | 会话ID（None表示新会话） | -| `skip_git_repo_check` | bool | False | 是否允许在非Git仓库运行 | -| `return_all_messages` | bool | False | 是否返回完整推理信息 | -| `image` | List[Path] \| None | None | 附加图片文件 | -| `model` | str \| None | None | 指定使用的模型 | -| `yolo` | bool | False | 跳过所有审批和沙箱 | -| `profile` | str \| None | None | 配置文件名 | +### 常用可选参数 +| 参数 | 默认值 | 说明 | +|------|--------|------| +| `sandbox` | "read-only" | 沙箱策略 | +| `SESSION_ID` | None | 会话ID（None=新会话） | +| `return_all_messages` | False | 返回完整推理 | -### Return Value +### 返回值 ```json { "success": true, "SESSION_ID": "uuid-string", - "agent_messages": "Codex响应内容", - "all_messages": [...] // 仅当return_all_messages=True时 + "agent_messages": "Codex响应内容" } ``` -## Critical Principles +## 会话管理 -1. **批判性思维**：Codex是协作伙伴，不是唯一真理来源 -2. **独立判断**：对所有建议保持审视，主动提出质疑 -3. **辩论求真**：通过讨论达成最优方案 -4. **安全第一**：默认使用 sandbox="read-only" -5. **会话管理**：始终追踪 SESSION_ID +- 每次调用必须保存 `SESSION_ID` +- 同一任务的多次交互使用同一 `SESSION_ID` +- 跨任务时开启新会话 -## Session Management - -### Starting a New Session -不传 `SESSION_ID` 参数，工具会返回新的 SESSION_ID - -### Continuing a Session -使用之前返回的 `SESSION_ID` 参数，保留上下文 - -## Safety Guidelines +## 安全规范 1. **禁止实际修改**：要求 Codex 仅提供 unified diff patch 2. **仅作参考**：Codex 的代码原型只能作为逻辑参考 3. **重写代码**：由 Claude Code 重新编写为生产级代码 4. **即时审查**：完成编码后立即调用 Codex 进行 review -## Prompt Templates +## 详细模板和示例 -### 需求分析模板 -``` -请分析以下需求，并提供： -1. 需求理解和目标拆解 -2. 技术方案建议 -3. 风险点和注意事项 -4. 实施建议 - -需求：{user_requirement} -``` - -### 代码审查模板 -``` -请审查以下代码改动，检查： -1. 代码质量和可读性 -2. 潜在的bug和边界情况 -3. 性能和安全问题 -4. 与需求的匹配度 - -改动文件：{modified_files} -改动说明：{change_description} -``` - -### 方案设计模板 -``` -请设计以下功能的实现方案： -1. 整体架构设计 -2. 模块划分和接口定义 -3. 关键技术点 -4. 实施步骤 - -功能需求：{feature_requirement} -``` - -## Examples - -### Example 1: 代码定位和Bug修复 -``` -# 1. 调用 Codex 定位问题 -codex(PROMPT="搜索项目中处理用户认证的相关代码", cd="/project") - -# 2. 基于 Codex 的定位结果，Claude Code 分析问题 -# 3. Claude Code 编写修复代码 -# 4. 调用 Codex 审查修复 -codex(PROMPT="审查以下代码改动...", SESSION_ID=previous_session) -``` - -### Example 2: 新功能开发 -``` -# 1. 调用 Codex 进行需求分析 -codex(PROMPT="分析以下需求并设计实施方案...", cd="/project") - -# 2. 多轮讨论完善方案 -codex(PROMPT="关于你的方案，我有以下疑问...", SESSION_ID=session_1) - -# 3. Claude Code 基于方案编写代码 -# 4. Codex 审查代码 -codex(PROMPT="请审查已完成的代码实现", SESSION_ID=session_1) -``` +- **代码审查模板**：见 [references/code-review.md](references/code-review.md) +- **需求分析模板**：见 [references/requirement-analysis.md](references/requirement-analysis.md) +- **方案设计模板**：见 [references/design-proposal.md](references/design-proposal.md) +- **调试分析模板**：见 [references/debug-analysis.md](references/debug-analysis.md) +- **完整会话示例**：见 [references/complete-session.md](references/complete-session.md)