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>

codex-collab/references/code-review.md

@@ -0,0 +1,96 @@
+# Code Review Template
+
+## Template Variables
+- `{modified_files}`: List of modified files
+- `{change_description}`: Description of changes made
+- `{requirement}`: Original requirement/user story
+
+## Prompt Template
+
+```
+请作为资深代码审查专家，审查以下代码改动：
+
+## 改动文件列表
+{modified_files}
+
+## 改动说明
+{change_description}
+
+## 原始需求
+{requirement}
+
+## 审查检查清单
+
+请按以下维度进行审查：
+
+### 1. 正确性 (Correctness)
+- [ ] 代码逻辑是否正确实现了需求
+- [ ] 是否有明显的bug或逻辑错误
+- [ ] 边界条件和异常情况是否处理
+- [ ] 数据验证是否充分
+
+### 2. 代码质量 (Code Quality)
+- [ ] 代码可读性和可维护性
+- [ ] 命名是否清晰准确
+- [ ] 是否有重复代码
+- [ ] 函数和类的职责是否单一
+
+### 3. 性能 (Performance)
+- [ ] 是否有明显的性能问题
+- [ ] 资源使用是否合理
+- [ ] 是否有不必要的计算或IO操作
+- [ ] 算法复杂度是否合理
+
+### 4. 安全性 (Security)
+- [ ] 是否有安全漏洞
+- [ ] 输入验证是否充分
+- [ ] 敏感信息是否正确处理
+- [ ] 权限检查是否完善
+
+### 5. 测试覆盖 (Testing)
+- [ ] 关键逻辑是否有测试覆盖
+- [ ] 测试用例是否充分
+- [ ] 边界条件是否测试
+
+### 6. 文档 (Documentation)
+- [ ] 复杂逻辑是否有注释
+- [ ] API文档是否完整
+- [ ] 变更日志是否更新
+
+## 审查结论
+
+请提供：
+1. 总体评价（优秀/良好/需改进/不合格）
+2. 主要优点（1-3点）
+3. 必须修复的问题（如有）
+4. 建议改进的地方（如有）
+5. 其他意见
+```
+
+## Usage Example
+
+```python
+# After completing code changes
+modified_files = """
+- src/auth/login.py: 添加用户登录验证
+- src/auth/jwt.py: 实现JWT token生成和验证
+- tests/test_login.py: 添加登录测试用例
+"""
+
+change_description = """
+实现了基于JWT的用户认证系统：
+1. 用户登录验证（用户名+密码）
+2. JWT token生成和验证
+3. token过期处理
+4. 单元测试覆盖
+"""
+
+requirement = "实现用户登录功能，支持JWT token认证"
+
+# Call Codex for review
+codex(
+    PROMPT=f"<review template with variables>",
+    cd="/project",
+    SESSION_ID=previous_session
+)
+```

codex-collab/references/complete-session.md

@@ -0,0 +1,326 @@
+# 完整协作会话示例
+
+## 场景：实现用户认证功能
+
+### 阶段 1：需求分析
+
+**用户需求**：
+```
+我需要为我的 FastAPI 应用添加用户认证功能，包括：
+1. 用户注册（邮箱+密码）
+2. 用户登录（返回JWT token）
+3. Token验证中间件
+4. 密码重置功能
+```
+
+**Claude Code 调用 Codex**：
+```python
+# 第一阶段：需求分析
+codex(
+    PROMPT="""
+    请分析以下用户认证需求，并提供：
+    1. 需求理解和目标拆解
+    2. 技术方案建议
+    3. 风险点和注意事项
+    4. 实施建议
+
+    需求：
+    - 用户注册（邮箱+密码）
+    - 用户登录（返回JWT token）
+    - Token验证中间件
+    - 密码重置功能
+
+    项目背景：
+    - FastAPI 应用
+    - PostgreSQL 数据库
+    - 已有用户表（id, email, created_at）
+    """,
+    cd="/project",
+    sandbox="read-only",
+    return_all_messages=False
+)
+```
+
+**Codex 返回**：
+```json
+{
+  "success": true,
+  "SESSION_ID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "agent_messages": "## 需求分析结果\n\n### 1. 需求理解\n核心需求是实现完整的用户认证系统...\n\n### 2. 技术方案建议\n- 使用 passlib 进行密码哈希\n- 使用 python-jose 处理 JWT\n- 使用 FastAPI Depends 实现中间件\n\n### 3. 风险点\n- 密码安全：必须使用 bcrypt 且 salt rounds >= 12\n- Token 安全：使用 RS256 签名，设置合理过期时间\n- 密码重置：需要安全的 token 生成机制\n\n### 4. 实施建议\n按以下顺序实现：\n1. 密码哈希工具\n2. JWT 工具\n3. 注册端点\n4. 登录端点\n5. 认证中间件\n6. 密码重置"
+}
+```
+
+---
+
+### 阶段 2：方案讨论
+
+**Claude Code 继续讨论**：
+```python
+# 使用同一 SESSION_ID 继续对话
+codex(
+    PROMPT="""
+    关于你的方案，我有几个疑问：
+
+    1. 关于密码重置，你建议使用什么机制生成重置 token？
+    2. JWT 的过期时间建议设置为多长？
+    3. 是否需要实现 refresh token 机制？
+    4. 数据库是否需要新增字段？
+
+    请详细说明。
+    """,
+    cd="/project",
+    SESSION_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    sandbox="read-only"
+)
+```
+
+**Codex 返回详细解答**...
+
+---
+
+### 阶段 3：请求代码原型
+
+**Claude Code 请求原型**：
+```python
+# 请求代码原型（仅 unified diff patch）
+codex(
+    PROMPT="""
+    基于我们讨论的方案，请提供代码实现原型。
+
+    **重要要求**：
+    - 仅提供 unified diff patch 格式
+    - 不要实际修改任何代码
+    - 包含完整的类型注解
+    - 关键逻辑添加注释说明
+
+    需要实现的模块：
+    1. src/auth/password.py - 密码哈希工具
+    2. src/auth/jwt.py - JWT 工具
+    3. src/api/endpoints/auth.py - 认证端点
+    4. src/auth/dependencies.py - FastAPI 依赖
+
+    请按文件分别提供 diff。
+    """,
+    cd="/project",
+    SESSION_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    sandbox="read-only"
+)
+```
+
+---
+
+### 阶段 4：Claude Code 实现
+
+**Claude Code 基于 Codex 的原型，重新编写生产级代码**：
+```python
+# Claude Code 使用 Edit 工具编写实际代码
+
+# 1. 创建密码哈希模块
+# src/auth/password.py
+from passlib.context import CryptContext
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """验证密码"""
+    return pwd_context.verify(plain_password, hashed_password)
+
+def get_password_hash(password: str) -> str:
+    """生成密码哈希"""
+    return pwd_context.hash(password)
+
+# 2. 创建 JWT 工具模块
+# src/auth/jwt.py
+from datetime import datetime, timedelta
+from jose import JWTError, jwt
+from typing import Optional
+
+SECRET_KEY = "your-secret-key-here"
+ALGORITHM = "HS256"
+
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None):
+    """创建访问令牌"""
+    to_encode = data.copy()
+    expire = datetime.utcnow() + (expires_delta or timedelta(minutes=15))
+    to_encode.update({"exp": expire})
+    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
+
+# 3. 创建认证端点
+# src/api/endpoints/auth.py
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel
+
+router = APIRouter()
+
+class LoginRequest(BaseModel):
+    email: str
+    password: str
+
+@router.post("/login")
+async def login(req: LoginRequest):
+    # 实现登录逻辑
+    pass
+
+# 4. 创建认证依赖
+# src/auth/dependencies.py
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+security = HTTPBearer()
+
+async def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(security)):
+    """获取当前用户"""
+    # 实现 token 验证逻辑
+    pass
+```
+
+---
+
+### 阶段 5：代码审查
+
+**Claude Code 完成编码后，立即请求审查**：
+```python
+# 请求 Codex 审查代码
+codex(
+    PROMPT=f"""
+    请审查以下代码改动：
+
+    ## 改动文件列表
+    - src/auth/password.py（新建）：密码哈希工具
+    - src/auth/jwt.py（新建）：JWT 工具
+    - src/api/endpoints/auth.py（新建）：认证端点
+    - src/auth/dependencies.py（新建）：认证依赖
+
+    ## 改动说明
+    实现了完整的用户认证系统：
+    1. 使用 bcrypt 进行密码哈希（salt rounds=12）
+    2. 使用 HS256 算法生成 JWT，默认15分钟过期
+    3. 提供 /login 和 /register 端点
+    4. 实现 get_current_user 依赖用于保护路由
+
+    ## 原始需求
+    实现用户注册、登录、Token验证和密码重置功能
+
+    请按以下维度审查：
+    1. 正确性 - 是否正确实现需求
+    2. 代码质量 - 可读性和可维护性
+    3. 安全性 - 密码和 token 安全
+    4. 边界情况 - 异常处理
+    5. 测试覆盖 - 是否需要测试
+
+    请提供：
+    1. 总体评价
+    2. 必须修复的问题（如有）
+    3. 建议改进的地方
+    """,
+    cd="/project",
+    SESSION_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+)
+```
+
+**Codex 审查结果**：
+```json
+{
+  "success": true,
+  "agent_messages": "## 审查结果\n\n### 总体评价：良好\n\n### 必须修复的问题：\n1. SECRET_KEY 硬编码在代码中，应该从环境变量读取\n2. 缺少密码强度验证\n3. jwt.decode() 没有异常处理\n\n### 建议改进：\n1. 建议添加 refresh token 机制\n2. 密码重置功能还未实现\n3. 建议添加速率限制防止暴力破解\n4. 建议添加日志记录"
+}
+```
+
+---
+
+### 阶段 6：根据审查调整
+
+**Claude Code 根据审查意见进行调整**：
+```python
+# 修复必须修复的问题
+
+# 1. 修改 jwt.py，从环境变量读取 SECRET_KEY
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+SECRET_KEY = os.getenv("JWT_SECRET_KEY")
+if not SECRET_KEY:
+    raise ValueError("JWT_SECRET_KEY environment variable is not set")
+
+# 2. 添加密码强度验证
+# src/auth/validators.py
+import re
+
+def validate_password_strength(password: str) -> bool:
+    """验证密码强度"""
+    if len(password) < 8:
+        return False
+    if not re.search(r"[A-Z]", password):
+        return False
+    if not re.search(r"[a-z]", password):
+        return False
+    if not re.search(r"\d", password):
+        return False
+    return True
+
+# 3. 添加 JWT 异常处理
+# src/auth/jwt.py
+def decode_token(token: str):
+    """解码 JWT token"""
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+        return payload
+    except JWTError as e:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Invalid token: {str(e)}"
+        )
+```
+
+---
+
+### 阶段 7：最终审查
+
+**Claude Code 再次请求审查**：
+```python
+codex(
+    PROMPT="""
+    我已根据你的审查意见进行了修复：
+    1. SECRET_KEY 从环境变量读取
+    2. 添加了密码强度验证
+    3. 添加了 JWT 异常处理
+
+    请再次审查，确认是否还有问题。
+    """,
+    cd="/project",
+    SESSION_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+)
+```
+
+---
+
+## 协作流程总结
+
+```
+用户需求
+    ↓
+[阶段1] Codex 需求分析 → 获得 SESSION_ID
+    ↓
+[阶段2] 多轮讨论完善方案 → 使用同一 SESSION_ID
+    ↓
+[阶段3] 请求代码原型（unified diff）→ 使用同一 SESSION_ID
+    ↓
+[阶段4] Claude Code 重写生产级代码
+    ↓
+[阶段5] Codex 代码审查 → 使用同一 SESSION_ID
+    ↓
+[阶段6] 根据审查调整代码
+    ↓
+[阶段7] 最终审查确认 → 使用同一 SESSION_ID
+    ↓
+完成
+```
+
+## 关键要点
+
+1. **始终使用同一 SESSION_ID**：保持上下文连贯
+2. **批判性思维**：对 Codex 的建议保持审视
+3. **安全优先**：使用 sandbox="read-only"
+4. **重写代码**：基于原型编写生产级代码
+5. **即时审查**：完成后立即让 Codex review

codex-collab/references/debug-analysis.md

@@ -0,0 +1,128 @@
+# Debug Analysis Template
+
+## Template Variables
+- `{error_message}`: Error message or stack trace
+- `{reproduction_steps}`: Steps to reproduce the issue
+- `{context}`: What was happening when the error occurred
+- `{recent_changes}`: Recent code changes that might be related
+
+## Prompt Template
+
+```
+请作为调试专家，帮助分析和定位以下问题：
+
+## 错误信息
+```
+{error_message}
+```
+
+## 复现步骤
+{reproduction_steps}
+
+## 问题背景
+{context}
+
+## 最近改动
+{recent_changes}
+
+## 分析要求
+
+请提供：
+
+### 1. 问题定位
+- 定位到具体的代码位置（文件:行号）
+- 说明问题发生的直接原因
+- 分析问题的根本原因
+
+### 2. 影响范围
+- 影响哪些功能模块
+- 影响的用户场景
+- 问题的严重程度评估
+
+### 3. 可能的解决方案
+- 推荐的修复方案（优先级排序）
+- 每个方案的优缺点
+- 推荐方案的实现要点
+
+### 4. 预防措施
+- 如何避免类似问题
+- 需要添加的测试
+- 需要改进的地方
+
+### 5. 验证方法
+- 如何验证问题已修复
+- 需要测试的场景
+- 回归测试建议
+
+## 输出格式
+
+1. **问题诊断**（一句话总结）
+2. **根本原因分析**（详细说明）
+3. **修复方案**（推荐方案+实现建议）
+4. **验证清单**
+
+## 搜索指令
+
+请先搜索相关代码：
+1. 搜索错误信息中的关键函数或类
+2. 搜索相关的模块和文件
+3. 查找最近的代码变更
+4. 分析调用栈
+```
+
+## Usage Example
+
+```python
+# When encountering a bug
+error_message = """
+AssertionError: User should be authenticated
+Traceback:
+  File "/app/src/api/endpoints/orders.py", line 45, in create_order
+    assert current_user.is_authenticated, "User should be authenticated"
+  File "/app/src/auth/deps.py", line 23, in get_current_user
+    user = decode_token(token)
+  File "/app/src/auth/jwt.py", line 67, in decode_token
+    raise ExpiredTokenError()
+"""
+
+reproduction_steps = """
+1. 用户登录后获取 token
+2. 等待 30 分钟
+3. 使用该 token 创建订单
+4. 收到认证错误
+"""
+
+context = """
+订单创建接口需要用户认证，使用 JWT token。
+token 有效期设置为 1 小时。
+问题：用户在 token 有效期内但仍然收到认证失败错误。
+"""
+
+recent_changes = """
+昨天修改了 JWT 解码逻辑，优化了 token 验证流程。
+"""
+
+# Call Codex for debug analysis
+codex(
+    PROMPT=f"""
+    <debug template with variables>
+
+    请先搜索以下内容：
+    1. src/auth/jwt.py 中的 decode_token 函数
+    2. src/api/endpoints/orders.py 中的 create_order 函数
+    3. src/auth/deps.py 中的 get_current_user 函数
+    4. 查找最近对 jwt.py 的修改
+    """,
+    cd="/project",
+    sandbox="read-only"
+)
+```
+
+## Follow-up Actions
+
+After receiving debug analysis:
+1. Verify Codex's diagnosis by examining the code
+2. Discuss the proposed solution if needed
+3. Implement the fix
+4. Ask Codex to review the fix
+5. Add tests to prevent regression

codex-collab/references/design-proposal.md

@@ -0,0 +1,155 @@
+# Design Proposal Template
+
+## Template Variables
+- `{feature_requirement}`: Feature requirement description
+- `{analysis_result}`: Results from requirement analysis
+- `{current_architecture}`: Current system architecture
+- `{tech_stack}`: Current technology stack
+
+## Prompt Template
+
+```
+请作为系统架构师，设计以下功能的详细实现方案：
+
+## 功能需求
+{feature_requirement}
+
+## 需求分析结果
+{analysis_result}
+
+## 当前架构
+{current_architecture}
+
+## 技术栈
+{tech_stack}
+
+## 设计要求
+
+请提供以下内容：
+
+### 1. 整体设计
+- 系统架构图（文字描述）
+- 模块划分和职责
+- 模块间的交互关系
+- 数据流设计
+
+### 2. 接口设计
+- API接口定义
+- 请求/响应格式
+- 错误码定义
+- 接口调用流程
+
+### 3. 数据模型设计
+- 数据库表结构
+- 字段定义和类型
+- 索引设计
+- 数据关系
+
+### 4. 核心逻辑设计
+- 关键算法或逻辑流程
+- 状态机设计（如适用）
+- 并发控制
+- 异常处理策略
+
+### 5. 技术选型
+- 使用的技术和框架
+- 第三方库选择
+- 技术选择的理由
+- 潜在的替代方案
+
+### 6. 安全设计
+- 认证和授权
+- 数据加密
+- 输入验证
+- 防护措施
+
+### 7. 性能考虑
+- 性能目标
+- 优化策略
+- 缓存设计
+- 扩展性考虑
+
+### 8. 实施计划
+- 开发阶段划分
+- 每个阶段的交付物
+- 依赖关系
+- 里程碑
+
+### 9. 测试策略
+- 单元测试策略
+- 集成测试策略
+- 性能测试策略
+- 测试数据准备
+
+### 10. 部署和运维
+- 部署方案
+- 配置管理
+- 监控指标
+- 回滚方案
+
+## 输出要求
+
+请提供：
+1. **设计摘要**（高层概览，200字以内）
+2. **详细设计**（按上述10个维度）
+3. **实施检查清单**（按优先级排序）
+4. **风险和缓解措施**
+
+## 代码原型要求
+
+如需提供代码原型：
+- 仅提供 unified diff patch 格式
+- 不要实际修改代码
+- 代码需要包含完整的类型注解
+- 关键逻辑需要添加注释说明
+```
+
+## Usage Example
+
+```python
+# After requirement analysis is complete
+feature_requirement = """
+实现一个基于WebSocket的实时消息推送系统
+"""
+
+analysis_result = """
+从需求分析中得出的关键发现：
+- 需要支持10万+并发连接
+- 消息延迟需控制在100ms以内
+- 需要支持消息持久化
+- 需要支持离线消息
+"""
+
+current_architecture = """
+微服务架构，使用：
+- API Gateway
+- 用户服务
+- 消息服务
+- 推送服务（待实现）
+"""
+
+tech_stack = """
+- 后端：Python 3.11 + FastAPI
+- 数据库：PostgreSQL 15
+- 缓存：Redis 7
+- 消息队列：RabbitMQ
+- 容器：Docker + Kubernetes
+"""
+
+# Call Codex for design
+codex(
+    PROMPT=f"<design template with variables>",
+    cd="/project",
+    SESSION_ID=analysis_session,  # Continue from analysis
+    sandbox="read-only"
+)
+```
+
+## Follow-up Actions
+
+After receiving design proposal:
+1. Review the design critically
+2. Ask questions about unclear parts
+3. Discuss alternative approaches
+4. Iterate on the design
+5. Once approved, proceed to implementation

codex-collab/references/requirement-analysis.md

@@ -0,0 +1,102 @@
+# Requirement Analysis Template
+
+## Template Variables
+- `{user_requirement}`: User's original requirement
+- `{context}`: Project context and background
+- `{constraints}`: Known constraints or limitations
+
+## Prompt Template
+
+```
+请作为技术架构专家，深入分析以下需求：
+
+## 用户需求
+{user_requirement}
+
+## 项目背景
+{context}
+
+## 已知约束
+{constraints}
+
+## 分析要求
+
+请提供以下维度的分析：
+
+### 1. 需求理解
+- 需求的核心目标是什么
+- 涉及哪些功能模块
+- 用户期望达到什么效果
+- 需求的优先级和紧急程度
+
+### 2. 技术可行性
+- 现有技术栈能否支持
+- 是否需要引入新技术或依赖
+- 技术难点在哪里
+- 预估的技术风险
+
+### 3. 影响范围评估
+- 涉及哪些模块和组件
+- 是否有现有功能需要调整
+- 是否影响现有数据和API
+- 兼容性考虑
+
+### 4. 实施方案建议
+- 推荐的技术方案
+- 实施步骤拆解
+- 关键技术点和注意事项
+- 潜在的替代方案
+
+### 5. 风险识别
+- 技术风险
+- 业务风险
+- 兼容性风险
+- 性能风险
+
+### 6. 测试策略
+- 需要测试的场景
+- 测试类型建议
+- 关键测试点
+
+## 输出格式
+
+请以结构化的方式输出，包括：
+1. 需求摘要（1-2句话）
+2. 详细分析（按上述维度）
+3. 推荐方案（优先推荐1个方案，可附带备选）
+4. 行动检查清单
+```
+
+## Usage Example
+
+```python
+# When user provides a new requirement
+user_requirement = """
+实现一个实时通知系统，支持：
+1. 用户可以订阅不同类型的通知
+2. 支持多种通知渠道（邮件、短信、推送）
+3. 通知可以延迟发送
+4. 用户可以自定义通知规则
+"""
+
+context = """
+当前系统是一个SaaS平台，使用：
+- 后端：Python + FastAPI
+- 前端：React + TypeScript
+- 数据库：PostgreSQL + Redis
+- 消息队列：RabbitMQ
+"""
+
+constraints = """
+- 需要保持向后兼容
+- 通知发送不能阻塞主流程
+- 成本控制在合理范围内
+"""
+
+# Call Codex for analysis
+codex(
+    PROMPT=f"<analysis template with variables>",
+    cd="/project",
+    sandbox="read-only"
+)
+```