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 <noreply@anthropic.com>
This commit is contained in:
empty
2026-01-11 17:22:33 +08:00
parent ccd8f9dbfb
commit 15604b53c5
8 changed files with 65 additions and 517 deletions

View File

@@ -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 重新开始
```

View File

@@ -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**

View File

@@ -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 | 会话IDNone表示新会话) |
| `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 | 会话IDNone=新会话) |
| `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)