README

# Skills 技能系统指南

Claude Code 技能系统允许你定义可复用的专业知识、工作流和自动化。

## 按场景快速选择技能

### 我要写代码

| 场景              | 推荐技能               | 调用方式                   |
| ----------------- | ---------------------- | -------------------------- |
| 后端开发 (Python) | `backend` → python.md  | `/backend` 然后选 Python   |
| 后端开发 (Java)   | `backend` → java.md    | `/backend` 然后选 Java     |
| 后端开发 (Rust)   | `backend` → rust.md    | `/backend` 然后选 Rust     |
| 前端开发 (Vue)    | `frontend` → vue.md    | `/frontend` 然后选 Vue     |
| 前端开发 (React)  | `frontend` → react.md  | `/frontend` 然后选 React   |
| iOS/macOS 开发    | `native` → ios.md      | `/native` 然后选 iOS       |
| Tauri 桌面应用    | `native` → tauri.md    | `/native` 然后选 Tauri     |
| API 设计          | `api`                  | `/api`                     |
| 数据库设计        | `database`             | `/database`                |

### 我要测试

| 场景          | 推荐技能                  | 调用方式               |
| ------------- | ------------------------- | ---------------------- |
| 测试驱动开发  | `testing` → tdd.md        | `/testing` 然后选 TDD  |
| E2E 端到端    | `testing` → e2e.md        | `/testing` 然后选 E2E  |
| 查看测试示例  | `testing` → tdd-example.md| 读取 tdd-example.md    |

### 我要审查/调试

| 场景          | 推荐技能               | 调用方式                            |
| ------------- | ---------------------- | ----------------------------------- |
| 安全审查      | `security`             | `/security` 或调用 security-reviewer agent |
| 代码审查      | `code-reviewer` agent  | 让 Claude 调用 code-reviewer agent  |
| 系统化调试    | `debug`                | `/debug`                            |
| 第二意见      | `second-opinion`       | `/second-opinion`                   |

### 我要管理会话

| 场景            | 推荐技能       | 调用方式         |
| --------------- | -------------- | ---------------- |
| 压缩上下文      | `compact`      | `/compact`       |
| 提取学习内容    | `learning`     | `/learning`      |
| 探索代码库      | `exploration`  | `/exploration`   |

### 命令与技能映射

```
开始新功能：/pm → /lead → /designer → /dev → /qa
代码审查：  完成编码 → 调用 code-reviewer agent
调试问题：  /debug → 系统化排查
提交代码：  /commit
压缩上下文：/compact
```

---

## 什么是 Skill？

Skill 是一个包含 `SKILL.md` 文件的文件夹，可以包含：

- 指令和最佳实践
- 参考文件
- 可执行脚本

## 技能分类

本项目采用**父子技能结构**组织技能，便于按需加载：

### 开发技能（独立）

| 技能           | 描述                             |
| -------------- | -------------------------------- |
| `backend`      | 后端开发模式（Python, TS, Java, Go, C#, Rust） |
| `frontend`     | 前端开发模式（Vue, React, Svelte, Angular）|
| `database`     | 数据库模式（PostgreSQL, MySQL, Oracle, SQLite）|
| `devops`       | DevOps 模式（Docker, CI/CD）       |
| `api`          | RESTful API 设计（Express, FastAPI, Next.js）|
| `git`          | Git 工作流最佳实践                |
| `architecture` | 架构设计（ADR、设计检查清单、角色方法论）|
| `second-opinion` | 第二意见/多模型交叉验证         |

### 测试技能

| 技能      | 描述                               |
| --------- | ---------------------------------- |
| `testing` | 测试策略和方法论（含 TDD、E2E）    |

子文件：`tdd.md`、`e2e.md`、`tdd-example.md`、`frameworks.md`、`qa-methodology.md`

### 质量技能（父子结构）

| 父/子    | 技能       | 描述                               |
| -------- | ---------- | ---------------------------------- |
| **父**   | `quality`  | 代码质量保障策略总览               |
| 子       | `security` | 安全审查（OWASP、密钥检测）        |
| 子       | `debug`    | 系统化调试方法                     |

### 会话技能（父子结构）

| 父/子    | 技能      | 描述                               |
| -------- | --------- | ---------------------------------- |
| **父**   | `session` | 会话生命周期管理总览               |
| 子       | `learning`| 会话评估和知识提取                 |
| 子       | `compact` | 策略性上下文压缩                   |

### 探索技能

| 技能          | 描述                               |
| ------------- | ---------------------------------- |
| `exploration` | 代码库探索策略（隔离研究、迭代检索）|

子文件：`isolated-research.md`、`iterative-retrieval.md`

### 原生开发技能

| 技能     | 描述                               |
| -------- | ---------------------------------- |
| `native` | 原生/桌面应用开发策略（iOS/macOS、Tauri） |

子文件：`ios.md`、`swift-concurrency.md`、`swiftui-performance.md`、`tauri.md`

> **未来计划**: `native` 将包含 `android.md` 子文件

## 目录结构

```
skills/
├── README                       # 本文档
│
├── # === 独立技能 ===
├── api/
│   ├── SKILL.md                 # RESTful API 设计
│   ├── express.md               # Express.js API 模式
│   ├── fastapi.md               # FastAPI 模式
│   └── nextjs.md                # Next.js API 路由
├── architecture/
│   ├── SKILL.md                 # 架构设计（ADR、设计检查清单）
│   ├── lead-methodology.md      # Lead 角色方法论
│   └── pm-methodology.md        # PM 角色方法论
├── backend/
│   ├── SKILL.md                 # 后端通用模式
│   ├── python.md                # Python 特定模式
│   ├── python-patterns.md       # Python 设计模式
│   ├── python-types.md          # Python 类型系统
│   ├── python-observability.md  # Python 可观测性
│   ├── typescript.md            # TypeScript 特定模式
│   ├── java.md                  # Java 特定模式
│   ├── go.md                    # Go 特定模式
│   ├── csharp.md                # C# 特定模式
│   ├── rust.md                  # Rust 特定模式
│   └── performance.md           # 后端性能优化
├── database/
│   ├── SKILL.md                 # 数据库通用模式
│   ├── postgres.md              # PostgreSQL 最佳实践
│   ├── mysql.md                 # MySQL/MariaDB 最佳实践
│   ├── oracle.md                # Oracle 最佳实践
│   └── sqlite.md                # SQLite 最佳实践
├── devops/
│   ├── SKILL.md                 # DevOps 通用模式
│   ├── docker.md                # Docker 最佳实践
│   └── ci-cd.md                 # CI/CD 流水线
├── frontend/
│   ├── SKILL.md                 # 前端通用模式
│   ├── vue.md                   # Vue 特定模式
│   ├── react.md                 # React 特定模式
│   ├── svelte.md                # Svelte 特定模式
│   ├── angular.md               # Angular 特定模式
│   ├── performance.md           # 前端性能优化
│   ├── tailwind.md              # Tailwind CSS 最佳实践
│   └── design-guide.md          # Designer 角色设计方法论
├── git/
│   ├── SKILL.md                 # Git 工作流最佳实践
│   ├── pr-workflow.md           # PR 创建与模板
│   ├── hooks-guide.md           # Git Hooks 配置
│   ├── delegation.md            # Agent 委派指南
│   └── commands-reference.md    # Git 命令速查
├── second-opinion/
│   └── SKILL.md                 # 第二意见/多模型交叉验证
│
├── # === 测试技能 ===
├── testing/
│   ├── SKILL.md                 # 测试策略总览
│   ├── tdd.md                   # TDD 工作流
│   ├── e2e.md                   # E2E 测试指南
│   ├── tdd-example.md           # 完整 TDD 会话示例
│   ├── frameworks.md            # 测试框架配置与 Mock 模式
│   └── qa-methodology.md        # QA 角色方法论
│
├── # === 质量技能族 ===
├── quality/
│   ├── SKILL.md                 # [父] 代码质量策略总览
│   └── code-health.md           # 代码健康度指标
├── security/
│   ├── SKILL.md                 # [子] 安全审查 (parent: quality)
│   ├── cloud-security.md        # 云基础设施安全
│   └── verify-checklist.md      # 安全验证检查清单
├── debug/
│   ├── SKILL.md                 # [子] 系统化调试 (parent: quality)
│   ├── frontend-debug.md        # 前端调试方法
│   ├── network-debug.md         # 网络调试方法
│   └── performance-debug.md     # 性能调试方法
│
├── # === 会话技能族 ===
├── session/
│   └── SKILL.md                 # [父] 会话生命周期管理
├── learning/
│   ├── SKILL.md                 # [子] 知识提取 (parent: session)
│   └── extraction-guide.md      # 会话学习方法论
├── compact/
│   └── SKILL.md                 # [子] 上下文压缩 (parent: session)
│
├── # === 探索技能 ===
├── exploration/
│   ├── SKILL.md                 # 代码库探索策略
│   ├── isolated-research.md     # 隔离研究（快速一次性）
│   └── iterative-retrieval.md   # 迭代检索（多轮精炼）
│
├── # === 原生开发技能 ===
└── native/
    ├── SKILL.md                 # 原生应用开发策略
    ├── ios.md                   # iOS/macOS 开发指南
    ├── swift-concurrency.md     # Swift 并发模式
    ├── swiftui-performance.md   # SwiftUI 性能优化
    └── tauri.md                 # Tauri 跨平台桌面应用
```

## SKILL.md Frontmatter 字段

所有字段都是可选的：

```yaml
---
name: my-skill
description: 技能描述，说明何时使用
argument-hint: [参数提示]
disable-model-invocation: true
user-invocable: false
allowed-tools: Read, Grep, Glob
model: sonnet
context: fork
agent: Explore
parent: parent-name
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
once: true
---
技能指令内容...
```

### 字段说明

| 字段                       | 类型    | 说明                                                          |
| -------------------------- | ------- | ------------------------------------------------------------- |
| `name`                     | string  | 显示名称（小写、连字符，最多 64 字符），变成 `/slash-command` |
| `description`              | string  | 何时使用此技能。Claude 用于自动调用决策                       |
| `argument-hint`            | string  | 自动补全提示（如 `[filename] [format]`）                      |
| `disable-model-invocation` | boolean | 阻止 Claude 自动调用，只能手动 `/name`                        |
| `user-invocable`           | boolean | 设为 `false` 隐藏在 `/` 菜单中，仅作背景知识                  |
| `allowed-tools`            | string  | Claude 可使用的工具（逗号分隔）                               |
| `model`                    | string  | 指定使用的模型（sonnet、opus、haiku）                         |
| `context`                  | string  | 设为 `fork` 在隔离的子代理上下文中运行                        |
| `agent`                    | string  | `context: fork` 时使用的子代理类型                            |
| `parent`                   | string  | **父技能名称**（用于主子技能结构）                            |
| `hooks`                    | object  | 技能生命周期钩子                                              |
| `once`                     | boolean | 设为 `true` 每个会话只运行一次                                |

## 子文件模式

### 什么是子文件模式？

将相关内容组织在同一技能目录下的子文件中，SKILL.md 作为入口和策略选择器：

```
testing/
├── SKILL.md           # 入口 - 策略选择指南
├── tdd.md             # 子文件 - TDD 流程
├── e2e.md             # 子文件 - E2E 流程
└── frameworks.md      # 子文件 - 框架配置
```

### 子文件引用

在 SKILL.md 中列出子文件：

```markdown
## 子文件

- [tdd.md](tdd.md) - TDD 工作流
- [e2e.md](e2e.md) - E2E 测试指南
```

### 使用场景

| 需求                 | 加载方式                     |
| -------------------- | ---------------------------- |
| 了解测试策略         | 加载 `testing` 技能          |
| Claude 按需读取详情  | 根据 SKILL.md 引用读取子文件 |

## 调用控制

### disable-model-invocation: true

- 你可以调用：是（`/skill-name`）
- Claude 可以调用：否
- 用例：`/deploy`、`/commit` 等有副作用的工作流

### user-invocable: false

- 你可以调用：否
- Claude 可以调用：是
- 用例：背景知识（如 `legacy-system-context`）

### 默认（两者都为 true）

- 你和 Claude 都可以调用

## Context: Fork - 隔离子代理执行

在分叉的子代理上下文中运行技能：

```yaml
---
name: deep-research
description: 深入研究一个主题
context: fork
agent: Explore
---
深入研究 $ARGUMENTS：

1. 使用 Glob 和 Grep 查找相关文件
2. 阅读和分析代码
3. 总结发现，包含具体文件引用
```

**关键点**：

- 技能内容成为子代理的提示
- 无法访问对话历史
- `agent` 字段决定执行环境（模型、工具、权限）
- 可用代理：`Explore`、`Plan`、`general-purpose` 或自定义 `agents/`

## 动态上下文注入

使用 `` !`command` `` 语法在技能执行前运行 shell 命令：

```yaml
---
name: pr-summary
description: 总结 Pull Request 的变更
context: fork
agent: Explore
---

## PR 上下文
- PR diff: !`gh pr diff`
- PR 评论: !`gh pr view --comments`
- 变更文件: !`gh pr diff --name-only`

## 任务
总结这个 Pull Request...
```

**注意**：这是预处理 - 命令在 Claude 看到技能**之前**执行。

## 字符串替换

技能内容中可用的变量：

| 变量                   | 说明                 |
| ---------------------- | -------------------- |
| `$ARGUMENTS`           | 调用时传递的所有参数 |
| `${CLAUDE_SESSION_ID}` | 当前会话 ID          |

## 技能中的 Hooks

技能支持生命周期钩子（作用域限定于该技能）：

```yaml
---
name: secure-ops
description: 带安全检查的操作
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---
```

支持的事件：`PreToolUse`、`PostToolUse`、`Stop`

## 工具限制

限制 Claude 的工具访问：

```yaml
---
name: safe-reader
description: 只读文件，不做修改
allowed-tools: Read, Grep, Glob
---
```

## 深度思考（Ultrathink）

在技能内容中包含 "ultrathink" 触发扩展思考：

```yaml
---
name: deep-analysis
description: 使用扩展思考进行深度分析
---
使用 ultrathink 模式，分析...
```

## 最佳实践

1. **保持 SKILL.md 聚焦** - 详细参考移到单独文件（< 500 行）
2. **写具体的描述** - Claude 用于自动调用决策
3. **有副作用时使用 `disable-model-invocation: true`** - 防止意外执行
4. **引用支持文件** - 告诉 Claude 每个文件包含什么以及何时加载
5. **用 `/skill-name` 测试** - 在依赖自动调用前验证行为
6. **使用父子结构** - 相关技能组织为父子关系，便于按需加载

## 技能热重载

修改 `skills/` 中的技能后**立即生效**，无需重启会话。

## 故障排查

| 问题       | 解决方案                                                               |
| ---------- | ---------------------------------------------------------------------- |
| 技能不触发 | 检查描述关键词，用 `/skill-name` 直接调用验证                          |
| 触发太频繁 | 使描述更具体，添加 `disable-model-invocation: true`                    |
| 技能不可见 | 检查字符预算：`SLASH_COMMAND_TOOL_CHAR_BUDGET` 环境变量（默认 15,000） |

## 技能总览

| 技能                  | 结构         | 用途                                             |
| --------------------- | ------------ | ------------------------------------------------ |
| `api`                 | 主+3文件     | RESTful API 设计（Express, FastAPI, Next.js）    |
| `architecture`        | 主+2文件     | 架构设计（ADR、角色方法论）                      |
| `backend`             | 主+10文件    | 后端开发模式（Python, TS, Java, Go, C#, Rust）   |
| `database`            | 主+4数据库   | 数据库模式（PostgreSQL, MySQL, Oracle, SQLite）  |
| `devops`              | 主+2平台     | DevOps 模式（Docker, CI/CD）                     |
| `frontend`            | 主+7文件     | 前端开发模式（Vue, React, Svelte, Angular）      |
| `git`                 | 主+4文件     | Git 工作流最佳实践                               |
| `second-opinion`      | 单文件       | 第二意见/多模型交叉验证                          |
| `testing`             | 主+5文件     | 测试策略（TDD、E2E、QA 方法论）                  |
| `quality`             | **父**+1文件 | 代码质量策略总览                                 |
| `security`            | 子+2文件     | 安全审查（parent: quality）                      |
| `debug`               | 子+3文件     | 系统化调试（parent: quality）                    |
| `session`             | **父**       | 会话生命周期管理                                 |
| `learning`            | 子+1文件     | 知识提取（parent: session）                      |
| `compact`             | 子           | 上下文压缩（parent: session）                    |
| `exploration`         | 主+2文件     | 代码库探索（隔离研究、迭代检索）                 |
| `native`              | 主+4文件     | 原生/桌面应用开发（iOS、Swift、SwiftUI、Tauri）  |