一、项目简介

Agent Skills 是 Anthropic 推出的模块化能力扩展机制，让 LLM 能够按需加载专业领域知识与工作流。本仓库收录了 GudaStudio 开发的 Agent Skills 集合，实现 Claude 与其他 AI 模型、工具的无缝协作。

二、快速开始

0. 前置要求

[!IMPORTANT] 本项目使用于Python运行脚本，并要求版本在3.8以上，开发测试python版本为3.10.

1. 获取仓库

git clone --recurse-submodules https://github.com/GuDaStudio/skills
cd skills

本项目提供一键安装脚本，支持灵活选择安装范围和目标位置。

./install.sh --list

# 用户级安装（所有项目生效）
./install.sh --user --all

# 项目级安装（仅当前项目生效，需在项目根目录执行）
./install.sh --project --all

# 仅安装 collaborating-with-codex
./install.sh --user --skill collaborating-with-codex

# 安装多个指定 Skill
./install.sh --user -s collaborating-with-codex -s collaborating-with-gemini

./install.sh --target /your/custom/path --all

.\install.ps1 -List

# 用户级安装（所有项目生效）
.\install.ps1 -User -All

# 项目级安装（仅当前项目生效，需在项目根目录执行）
.\install.ps1 -Project -All

# 仅安装 collaborating-with-codex
.\install.ps1 -User -Skill collaborating-with-codex

# 安装多个指定 Skill
.\install.ps1 -User -Skill collaborating-with-codex -Skill collaborating-with-gemini

.\install.ps1 -Target C:\your\custom\path -All

3. 验证安装

4. （🎊可选，但强烈推荐）配置提示词

为让本SKILLS集合更加Claude Code等CLI，我们强烈推荐您在 ~/.claude/CLAUDE.md中 配置/追加 以下提示词。

[!IMPORTANT] 本全局提示词使用了auggie-mcp,可参考官方安装教程.

# Global Protocols
- 若任务简单，可不进行多模型协作，但**必须**立即中止所有行为，向用户报告不进行协作的具体原因，直到收到用户许可才可进行下一步行动。例如，向用户输出，“这是一个简单xx任务，无需多模型协作。您是否同意此任务下不再进行任何多模型协作过程？我会等待您的回复并严格遵循本次特定协作规则！”
- 严格遵守 **1. Workflow**。跳过任何phase均被视为 **危险级操作**，需要 *立即终止任务* 并向用户 *报告跳过的原因*。例如，向用户输出，“在当前的xx phase，我发现xx，所以下一xx phase的任务实质上已经被xx解决。您是否同意我跳过xx phase？我会等待，直到收到您确定的回复再继续下一phase行动！”
- 除极个别特殊情况外，始终 **强制**与 Codex/Gemini 协作（SKILLs形式`python /path/to/scripts/*.py --cd "/path/to/project" --PROMPT "Analyze..." [OPTIONS]`，**Run in the background**，**不设置** timeout）。

----
## 0. Core Instruction

### 0.1 交互与状态管理
- **语言协议**。与工具/模型交互：**英语**；与用户交互：**中文**。
- **会话连续性**。如果工具返回 `SESSION_ID`，立即存储；在调用工具之前，**思考**：“这是一个后续操作吗？”如果是，在命令后追加 `--SESSION_ID <ID>`；如果内核输出被截断，自动执行继续命令或循环，直到 `Unified Diff`（统一差异）在语法上完整。

### 0.2 异步操作（原子循环）
- **强制并行**。对于任何涉及 Codex/Gemini 或长时间运行脚本的任务，必须使用 **Run in the background**（**不设置** timeout）。
- **CLI 结构**。确保 CLI 调用遵循SKILLs定义，通常为：`python /path/to/scripts/*.py --cd "/path/to/project" --PROMPT "Analyze..." [OPTIONS]`

### 0.3 安全与代码主权
- **无写入权**。Codex/Gemini 对文件系统拥有 **零** 写入权限；在每个内核 PROMPT（提示词）中，显式追加：**"OUTPUT: Unified Diff Patch ONLY. Strictly prohibit any actual modifications."**
- **参考重构**。将获取到的其他模型的Uniffied Patch视为“脏原型（Dirty Prototype）”；**流程**：读取 Diff -> **思维沙箱**（模拟应用并检查逻辑） -> **重构**（清理） -> 最终代码。

### 0.4 代码风格
- 整体代码风格**始终定位**为，精简高效、毫无冗余。该要求同样适用于注释与文档，且对于这两者，严格遵循**非必要不形成**的核心原则。
- **仅对需求做针对性改动**，严禁影响用户现有的其他功能。

### 0.5 工作流程完整性
- **止损**：在当前阶段的输出通过验证之前，不要进入下一阶段。
- **报告**：必须向用户实时报告当前阶段和下一阶段。

----
## 1. Workflow

### Phase 1: 上下文全量检索 (Auggie Interface)
**执行条件**：在生成任何建议或代码前。
1.  **工具调用**：调用 `mcp__auggie-mcp__codebase-retrieval`。
2.  **检索策略**：
    - 禁止基于假设（Assumption）回答。
    - 使用自然语言（NL）构建语义查询（Where/What/How）。
    - **完整性检查**：必须获取相关类、函数、变量的完整定义与签名。若上下文不足，触发递归检索。
3.  **需求对齐**：若检索后需求仍有模糊空间，**必须**向用户输出引导性问题列表，直至需求边界清晰（无遗漏、无冗余）。


### Phase 2: 多模型协作分析 
1.  **分发输入**：：将用户的**原始需求**（不带预设观点）分发给 Codex 和 Gemini。注意，Codex/Gemini都有完善的CLI系统，所以**仅需给出入口文件和row index**(而非Snippet)。
2.  **方案迭代**：
    - 要求模型提供多角度解决方案。
    - 触发**交叉验证**：整合各方思路，进行迭代优化，在过程中执行逻辑推演和优劣势互补，直至生成无逻辑漏洞的 Step-by-step 实施计划。
3.  **强制阻断 (Hard Stop)**：向用户展示最终实施计划（含适度伪代码）；必须以加粗文本输出询问："Shall I proceed with this plan? (Y/N)"；立即终止当前回复。绝对禁止在收到用户明确的 "Y" 之前执行 Phase 3 或调用任何文件读取工具。

### Phase 3: 原型获取
- **Route A: 前端/UI/样式 (Gemini Kernel)**
  - **限制**：上下文 < 32k。gemini对于后端逻辑的理解有缺陷，其回复需要客观审视。
  - **指令**：请求 CSS/React/Vue 原型。以此为最终前端设计原型与视觉基准。
- **Route B: 后端/逻辑/算法 (Codex Kernel)**
  - **能力**：利用其逻辑运算与 Debug 能力。
  - **指令**：请求逻辑实现原型。
- **通用约束**：：在与Codex/Gemini沟通的任何情况下，**必须**在 Prompt 中**明确要求** 返回 `Unified Diff Patch`，严禁Codex/Gemini做任何真实修改。

### 第 4 阶段：编码实施
**执行准则**：
1.  **逻辑重构**：基于 Phase 3 的原型，去除冗余，**重写**为高可读、高可维护性、企业发布级代码。
2.  **文档规范**：非必要不生成注释与文档，代码自解释。
3.  **最小作用域**：变更仅限需求范围，**强制审查**变更是否引入副作用并做针对性修正。

### 第 5 阶段：审计与交付
1.  **自动审计**：变更生效后，**强制立即调用** Codex与Gemini **同时进行** Code Review，并进行整合修复。
2.  **交付**：审计通过后反馈给用户。

----

## 2. 资源矩阵

此矩阵定义了各阶段的**强制性**资源调用策略。Claude 作为**主控模型 (Orchestrator)**，必须严格根据当前 Workflow 阶段，按以下规格调度外部资源。

| Workflow Phase           | Functionality           | Designated Model / Tool                  | Input Strategy (Prompting)                                   | Strict Output Constraints                           | Critical Constraints & Behavior                              |
| :----------------------- | :---------------------- | :--------------------------------------- | :----------------------------------------------------------- | :-------------------------------------------------- | :----------------------------------------------------------- |
| **Phase 1**              | **Context Retrieval**   | **Auggie** (`mcp__auggie`)               | **Natural Language (English)**<br>Focus on: *What, Where, How* | **Raw Code / Definitions**<br>(Complete Signatures) | • **Forbidden:** `grep` / keyword search.<br>• **Mandatory:** Recursive retrieval until context is complete. |
| **Phase 2**              | **Analysis & Planning** | **Codex** AND **Gemini**<br>(Dual-Model) | **Raw Requirements (English)**<br>Minimal context required.  | **Step-by-Step Plan**<br>(Text & Pseudo-code)       | • **Action:** Cross-validate outputs from both models.<br>• **Goal:** Eliminate logic gaps before coding starts. |
| **Phase 3**<br>(Route A) | **Frontend / UI / UX**  | **Gemini**                               | **English**<br>Context Limit: **< 32k tokens**               | **Unified Diff Patch**<br>(Prototype Only)          | • **Truth Source:** The only authority for CSS/React/Vue styles.<br>• **Warning:** Ignore its backend logic suggestions. |
| **Phase 3**<br>(Route B) | **Backend / Logic**     | **Codex**                                | **English**<br>Focus on: Logic & Algorithms                  | **Unified Diff Patch**<br>(Prototype Only)          | • **Capability:** Use for complex debugging & algorithmic implementation.<br>• **Security:** **NO** file system write access allowed. |
| **Phase 4**              | **Refactoring**         | **Claude (Self)**                        | N/A (Internal Processing)                                    | **Production Code**                                 | • **Sovereignty:** You are the specific implementer.<br>• **Style:** Clean, efficient, no redundancy. Minimal comments. |
| **Phase 5**              | **Audit & QA**          | **Codex** AND **Gemini**<br>(Dual-Model) | **Unified Diff** + **Target File**<br>(English)              | **Review Comments**<br>(Potential Bugs/Edge Cases)  | • **Mandatory:** Triggered immediately after code changes.<br>• **Action:** Synthesize feedback into a final fix. |

三、Skills 详解

collaborating-with-codex

将编码任务委托给 OpenAI Codex CLI，适用于算法实现、Bug 分析和代码审查。

python scripts/codex_bridge.py --cd "/project" --PROMPT "分析认证流程"

# 开启新会话
python scripts/codex_bridge.py --cd "/project" --PROMPT "审查 login.py 的安全问题"

# 继续会话
python scripts/codex_bridge.py --cd "/project" --SESSION_ID "uuid-from-response" --PROMPT "针对发现的问题提供修复建议"

python scripts/codex_bridge.py --cd "/project" --PROMPT "生成添加日志功能的 unified diff"

collaborating-with-gemini

将编码任务委托给 Google Gemini CLI，适用于算法实现、Bug 分析和代码审查。

python scripts/gemini_bridge.py --cd "/project" --PROMPT "分析认证流程"

# 开启新会话
python scripts/gemini_bridge.py --cd "/project" --PROMPT "审查 login.py 的安全问题"

# 继续会话
python scripts/gemini_bridge.py --cd "/project" --SESSION_ID "uuid-from-response" --PROMPT "针对发现的问题提供修复建议"

返回值结构

两个 Skill 均返回统一的 JSON 格式：

成功时：

{
  "success": true,
  "SESSION_ID": "550e8400-e29b-41d4-a716-446655440000",
  "agent_messages": "模型回复内容...",
  "all_messages": []
}

失败时：

{
  "success": false,
  "error": "错误信息描述"
}

四、FAQ

🤝 贡献指南

# 克隆仓库（含子模块）
git clone --recurse-submodules https://github.com/GuDaStudio/skills.git
cd skills

📄 许可证

本项目采用 MIT License 开源协议。

Copyright (c) 2025 guda.studio

GudaCC Skills 快速上手指南

Agent Skills 集合 —— 让 Claude Code 与 Codex、Gemini 等多模型无缝协作的模块化扩展工具。

一、环境准备

在开始之前，请确保您的开发环境满足以下要求：

1. 系统要求

• Python: 版本 3.8+ (推荐 3.10)
• 操作系统: Linux, macOS 或 Windows (PowerShell)

2. 前置依赖

请确保已安装并配置好以下核心工具：

• Claude Code: 版本 v2.0.56+
• Codex CLI: 若需使用 collaborating-with-codex
• Gemini CLI: 若需使用 collaborating-with-gemini

二、安装步骤

1. 获取项目

克隆仓库到本地任意目录：

git clone --recurse-submodules https://github.com/GuDaStudio/skills
cd skills

2. 执行安装

本项目提供一键安装脚本，支持灵活选择安装范围。

🐧 Linux / macOS

查看可用 Skills：

./install.sh --list

方式一：一键安装所有 Skills（推荐）

# 用户级安装（对所有项目生效）
./install.sh --user --all

# 项目级安装（仅对当前项目生效）
./install.sh --project --all

方式二：选择性安装

# 仅安装 Codex 协作技能
./install.sh --user --skill collaborating-with-codex

# 安装多个指定技能
./install.sh --user -s collaborating-with-codex -s collaborating-with-gemini

🪟 Windows (PowerShell)

查看可用 Skills：

.\install.ps1 -List

方式一：一键安装所有 Skills（推荐）

# 用户级安装
.\install.ps1 -User -All

# 项目级安装
.\install.ps1 -Project -All

方式二：选择性安装

# 仅安装 Codex 协作技能
.\install.ps1 -User -Skill collaborating-with-codex

参数说明：

• -User / --user: 安装至 ~/.claude/skills/
• -Project / --project: 安装至 ./.claude/skills/
• -All / --all: 安装所有可用技能
• -Skill / --skill: 指定安装特定技能

三、基本使用

1. 验证安装

启动 Claude Code，Skills 将自动加载。在对话框中输入以下指令进行验证：

list all available SKILLs please

若安装成功，Claude 应能识别并列出了 collaborating-with-codex 和 collaborating-with-gemini。

2. 简单调用示例

安装完成后，您可以直接通过自然语言让 Claude 调用这些技能。例如：

委托 Codex 进行代码审查：

"请使用 collaborating-with-codex 技能，分析当前目录下 login.py 文件的安全漏洞，并给出具体的修复建议。"

委托 Gemini 进行原型开发：

"调用 collaborating-with-gemini 技能，为当前的 React 组件生成一个包含新样式的 Unified Diff Patch。"

3. 进阶配置（强烈推荐）

为了发挥多模型协作的最大效能，建议在 ~/.claude/CLAUDE.md 中追加全局提示词协议。这将强制 Claude 遵循“检索 -> 多模型分析 -> 原型获取 -> 重构实施 -> 审计交付”的标准工作流，并确保所有外部模型调用均以后台运行且只输出 Diff 补丁（不直接修改文件），保障代码安全。

(具体配置内容可参考项目文档中的 Global Protocols 部分)