Claude Code Skills 完全指南

---
name: my-first-skill
description: 这是我的第一个 Skill，用于演示基本结构。当用户说"测试 Skill"时使用。
---

# 我的第一个 Skill

当用户请求帮助时，按以下步骤操作：

1. 首先说"你好，我是通过 Skill 激活的！"
2. 然后提供帮助
3. 最后问"还有什么我可以帮助的吗？"

测试 Skill

/my-first-skill

---
# ========== 元数据部分（YAML 格式）==========
name: skill-name           # 必填：Skill 名称（小写字母、数字、连字符）
description: 描述信息       # 必填：什么时候用这个 Skill（最多 1024 字符）
---

# ========== 指令部分（Markdown 格式）==========

这里写 Claude 需要遵循的指令...

# 问题：太模糊，Claude 不知道什么时候该用
description: 帮助写代码

# 问题：没有说明触发场景
description: 处理文档

# 好：说明了做什么 + 什么时候用 + 包含用户可能说的关键词
description: 生成符合 Conventional Commits 规范的 Git 提交信息。当用户要求提交代码、写 commit message、或者提到 git commit 时使用。

# 好：具体、有触发词
description: 从 PDF 文件中提取文本和表格，填写表单，合并文档。当用户提到 PDF、表单、文档提取时使用。

# 推荐的命名方式
name: processing-pdfs
name: analyzing-spreadsheets
name: reviewing-code
name: generating-docs

# 也可以接受
name: pdf-processing
name: code-review

# 避免
name: helper        # 太模糊
name: utils         # 太通用
name: my-tool       # 没有描述性

---
name: safe-reader
description: 安全地读取和分析代码
allowed-tools: Read, Grep, Glob
---

---
name: safe-reader
description: 安全地读取和分析代码
allowed-tools:
  - Read
  - Grep
  - Glob
---

# 只允许 git 相关命令
allowed-tools: Bash(git:*)

# 只允许特定的 git 命令
allowed-tools: Bash(git:status), Bash(git:diff), Bash(git:log)

# 允许 git 和 npm 命令
allowed-tools: Bash(git:*), Bash(npm:*)

# 允许 Python 和 Node.js
allowed-tools: Bash(python:*), Bash(node:*)

# 允许所有 Bash 命令（谨慎使用！）
allowed-tools: Bash

# 场景 1：只读分析
# 用途：代码分析、文档查阅
allowed-tools: Read, Grep, Glob

# 场景 2：Git 操作
# 用途：提交、查看历史
allowed-tools: Read, Bash(git:*)

# 场景 3：代码修改
# 用途：重构、格式化
allowed-tools: Read, Write, Edit, Grep, Glob

# 场景 4：测试运行
# 用途：运行单元测试
allowed-tools: Read, Bash(npm:test), Bash(pytest:*)

my-skill/
├── SKILL.md              # 必需：主文件（入口）
├── scripts/              # 可选：可执行脚本
│   ├── validate.py       # Python 脚本
│   └── format.sh         # Shell 脚本
├── references/           # 可选：参考文档
│   ├── api-docs.md       # API 文档
│   └── examples.md       # 示例代码
└── assets/               # 可选：静态资源
    ├── template.json     # 模板文件
    └── config.yaml       # 配置文件

bigquery-analysis/
├── SKILL.md              # 概览和导航
└── references/
    ├── finance.md        # 财务数据分析
    ├── sales.md          # 销售数据分析
    ├── product.md        # 产品数据分析
    └── marketing.md      # 营销数据分析

---
name: bigquery-analysis
description: 分析 BigQuery 数据，支持财务、销售、产品、营销等多种数据源
allowed-tools: Read, Grep
---

# BigQuery 数据分析

## 可用数据集

- **财务数据**：收入、账单 -> 参考 [references/finance.md](references/finance.md)
- **销售数据**：机会、管道 -> 参考 [references/sales.md](references/sales.md)
- **产品数据**：API 使用、功能 -> 参考 [references/product.md](references/product.md)
- **营销数据**：活动、归因 -> 参考 [references/marketing.md](references/marketing.md)

## 使用方法

1. 确定要分析的数据类型
2. 参考对应的文档了解表结构
3. 编写查询语句

pdf-processing/
├── SKILL.md              # 基础用法
├── FORMS.md              # 表单填写（进阶）
├── REFERENCE.md          # 完整 API 参考
└── scripts/
    └── extract.py        # 提取脚本

## 基础用法

提取 PDF 文本：

```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

**注意：避免嵌套引用**

```markdown
# 不好：引用链过长
SKILL.md -> advanced.md -> details.md -> actual-info.md

# 好：所有引用都在一级
SKILL.md -> advanced.md
SKILL.md -> details.md
SKILL.md -> api-reference.md

---
name: deep-analysis
description: 深度代码分析，生成详细报告
context: fork
agent: general-purpose
---

---
name: secure-deploy
description: 安全部署应用
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
          once: true
---

---
name: code-writer
description: 编写代码并自动格式化
hooks:
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: |
            file_path=$(jq -r '.tool_input.file_path')
            if [[ "$file_path" == *.py ]]; then
              black "$file_path" && isort "$file_path"
            elif [[ "$file_path" == *.ts ]]; then
              npx prettier --write "$file_path"
            fi
---

---
name: safe-editor
description: 安全编辑文件，阻止修改敏感文件
hooks:
  PreToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: |
            file_path=$(jq -r '.tool_input.file_path')
            if [[ "$file_path" == *.env* ]] || [[ "$file_path" == *credentials* ]]; then
              echo "ERROR: Cannot modify sensitive files" >&2
              exit 2  # exit 2 会阻止操作
            fi
            exit 0
---

---
name: audit-logger
description: 记录所有执行的命令
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: |
            jq -r '"[$(date)] " + .tool_input.command' >> ~/.claude/audit.log
---

---
name: session-logger
description: 记录当前会话的活动
---

# 会话日志

将以下内容记录到 `logs/${CLAUDE_SESSION_ID}.log`：

$ARGUMENTS

确保每条记录包含时间戳。

# Subagent: 文档分析员
---
name: doc-analyzer
description: 分析文档并生成报告
skills: pdf-extraction, text-summarization
---

1. 使用 pdf-extraction skill 提取文档内容
2. 使用 text-summarization skill 生成摘要
3. 返回结构化的分析报告

---
name: commit-helper
description: 生成符合 Conventional Commits 规范的提交信息。当用户要提交代码、写 commit message、或者说"帮我提交"时使用。
allowed-tools: Bash(git:*)
---

# Git 提交助手

## 工作流程

### 1. 检查状态

首先查看当前状态：

```bash
git status
```

### 2. 查看暂存区变更

```bash
git diff --cached --stat
```

如果没有暂存的变更，提示用户先 `git add`。

### 3. 查看详细变更

```bash
git diff --cached
```

### 4. 确定提交类型

根据变更内容选择合适的类型：

| 类型 | 说明 | 示例 |
|:-----|:-----|:-----|
| `feat` | 新功能 | feat(auth): 添加用户登录功能 |
| `fix` | 修复 bug | fix(api): 修复登录接口 500 错误 |
| `docs` | 文档变更 | docs: 更新 API 文档 |
| `style` | 代码格式（不影响功能） | style: 格式化代码 |
| `refactor` | 重构（不是新功能也不是修复） | refactor(user): 重构用户模块 |
| `perf` | 性能优化 | perf: 优化列表加载速度 |
| `test` | 添加或修改测试 | test: 添加登录单元测试 |
| `build` | 构建系统或外部依赖 | build: 升级 webpack 到 v5 |
| `ci` | CI 配置 | ci: 添加 GitHub Actions |
| `chore` | 其他不修改源码的变更 | chore: 更新 .gitignore |

### 5. 生成提交信息

格式：`<type>(<scope>): <description>`

规则：
- 第一行不超过 72 个字符
- 使用祈使句（"添加"而不是"添加了"）
- 不要以句号结尾
- scope 是可选的，表示影响范围

### 6. 展示并确认

展示生成的提交信息，等待用户确认后执行：

```bash
git commit -m "提交信息"
```

如果用户想修改，根据反馈调整。

---
name: code-review
description: 多轮代码审查，检查安全漏洞、性能问题和代码规范。当用户说 review、审查、检查代码时使用。
allowed-tools: Read, Grep, Glob, Bash(git:*)
---

# 代码审查助手

## 审查清单

复制此清单跟踪进度：

```
审查进度：
- [ ] 第一轮：变更概览
- [ ] 第二轮：深度分析
- [ ] 第三轮：整体评估
- [ ] 生成报告
```

## 第一轮：变更概览

### 1.1 获取变更文件

```bash
git diff --name-only HEAD~1
```

或者如果是 PR：

```bash
git diff --name-only main...HEAD
```

### 1.2 文件分类

将文件分为：
- **源代码**：.js, .ts, .py, .go 等
- **测试文件**：*_test.*, *.spec.*, test_* 等
- **配置文件**：.json, .yaml, .toml 等
- **文档**：.md, .txt 等

### 1.3 标记高风险区域

特别关注包含以下内容的文件：
- 认证/授权逻辑
- 数据库操作
- 文件系统操作
- 网络请求
- 加密/解密
- 用户输入处理

## 第二轮：深度分析

对每个高风险文件执行详细检查：

### 2.1 安全检查

搜索常见安全问题：

```bash
# SQL 注入风险
grep -n "execute\|query" --include="*.py" .

# XSS 风险
grep -n "innerHTML\|dangerouslySetInnerHTML" --include="*.tsx" --include="*.jsx" .

# 硬编码密钥
grep -n "password\|secret\|api_key\|token" --include="*.py" --include="*.js" .
```

### 2.2 性能检查

- N+1 查询问题
- 未使用的变量/导入
- 大循环中的 I/O 操作
- 未优化的正则表达式

### 2.3 代码质量检查

- 错误处理是否完善
- 边界条件是否处理
- 是否有代码重复
- 命名是否清晰

## 第三轮：整体评估

### 3.1 一致性检查

- 代码风格是否一致
- 命名规范是否统一
- 是否遵循项目约定

### 3.2 破坏性变更

- API 签名是否变化
- 数据库 schema 是否变化
- 配置格式是否变化

### 3.3 测试覆盖

- 新功能是否有测试
- 边界条件是否测试
- 错误路径是否测试

## 输出格式

```markdown
# 代码审查报告

## 概要
- 审查文件数：X
- 发现问题数：X（严重：X，警告：X，建议：X）

## 严重问题（必须修复）

### [问题标题]
- **文件**：path/to/file.py:42
- **问题**：具体描述
- **建议**：如何修复

## 警告（建议修复）

### [问题标题]
- **文件**：path/to/file.py:100
- **问题**：具体描述
- **建议**：如何修复

## 改进建议（可选）

- 建议 1
- 建议 2
```

pdf-processing/
├── SKILL.md
├── FORMS.md
├── scripts/
│   ├── extract_text.py
│   ├── extract_tables.py
│   └── fill_form.py
└── references/
    └── api-reference.md

---
name: pdf-processing
description: 从 PDF 提取文本和表格，填写表单，合并文档。当用户提到 PDF、表单、文档提取时使用。
allowed-tools: Read, Bash(python:*)
---

# PDF 处理

## 快速开始

### 提取文本

```bash
python scripts/extract_text.py input.pdf
```

输出：提取的文本内容

### 提取表格

```bash
python scripts/extract_tables.py input.pdf --output tables.json
```

输出：JSON 格式的表格数据

### 填写表单

详见 [FORMS.md](FORMS.md)

## 依赖

确保安装了必要的包：

```bash
pip install pdfplumber pypdf
```

## API 参考

完整的函数说明见 [references/api-reference.md](references/api-reference.md)

#!/usr/bin/env python3
"""从 PDF 提取文本"""
import sys
import pdfplumber

def extract_text(pdf_path: str) -> str:
    """提取 PDF 中的所有文本"""
    text_parts = []
    try:
        with pdfplumber.open(pdf_path) as pdf:
            for i, page in enumerate(pdf.pages, 1):
                page_text = page.extract_text()
                if page_text:
                    text_parts.append(f"=== 第 {i} 页 ===\n{page_text}")
        return "\n\n".join(text_parts)
    except Exception as e:
        return f"错误：{str(e)}"

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("用法：python extract_text.py <pdf_path>")
        sys.exit(1)

    result = extract_text(sys.argv[1])
    print(result)

# PDF 表单填写

## 分析表单

首先分析 PDF 中的表单字段：

```bash
python scripts/fill_form.py --analyze input.pdf
```

输出示例：

```json
{
  "fields": [
    {"name": "name", "type": "text", "page": 1},
    {"name": "email", "type": "text", "page": 1},
    {"name": "date", "type": "date", "page": 1}
  ]
}
```

## 填写表单

创建一个 JSON 文件包含要填写的值：

```json
{
  "name": "张三",
  "email": "zhangsan@example.com",
  "date": "2026-01-17"
}
```

然后填写：

```bash
python scripts/fill_form.py --fill input.pdf --data values.json --output filled.pdf
```

## 注意事项

- 确保字段名称匹配
- 日期格式使用 ISO 8601（YYYY-MM-DD）
- 复选框使用 true/false

ml-experiment-knowledge/
├── SKILL.md
└── experiments/
    ├── bert-fine-tuning.md
    ├── data-augmentation.md
    └── hyperparameter-search.md

---
name: ml-experiments
description: 机器学习实验知识库，包含已验证的配置、失败的尝试和最佳实践。当用户询问 ML 实验、模型训练、超参数时使用。
allowed-tools: Read, Grep
---

# ML 实验知识库

## 已验证的实验

### BERT 微调
- **成功配置**：参考 [experiments/bert-fine-tuning.md](experiments/bert-fine-tuning.md)
- 学习率：2e-5
- Batch size：32
- 预热步数：10% of total

### 数据增强
- **有效技术**：参考 [experiments/data-augmentation.md](experiments/data-augmentation.md)
- 同义词替换：效果好
- 回译：效果很好
- 随机删除：效果一般

### 超参数搜索
- **搜索策略**：参考 [experiments/hyperparameter-search.md](experiments/hyperparameter-search.md)
- 推荐使用 Optuna
- 早停策略很重要

## 失败的尝试（避免重复）

1. **学习率过大**：> 1e-4 会导致训练不稳定
2. **Batch 太小**：< 16 会导致梯度噪声大
3. **不使用预热**：容易在初期发散

## 使用方法

询问我关于：
- 特定模型的训练配置
- 数据增强技术
- 超参数调优策略
- 避免已知的坑

---
name: docx-editor
description: 编辑 Word 文档，支持修改文本、添加表格、更新样式。当用户要编辑 Word、docx 文件时使用。
allowed-tools: Read, Write, Bash(python:*)
---

# Word 文档编辑器

## 编辑工作流

复制此清单跟踪进度：

```
编辑进度：
- [ ] 1. 解压文档
- [ ] 2. 修改内容
- [ ] 3. 验证修改
- [ ] 4. 重新打包
- [ ] 5. 测试文档
```

## 步骤 1：解压文档

```bash
python scripts/unpack.py input.docx unpacked/
```

## 步骤 2：修改内容

编辑 `unpacked/word/document.xml`

## 步骤 3：验证修改（重要！）

**每次修改后立即验证：**

```bash
python scripts/validate.py unpacked/
```

如果验证失败：
1. 查看错误信息
2. 修复 XML
3. 重新验证
4. **验证通过后才能继续**

## 步骤 4：重新打包

```bash
python scripts/pack.py unpacked/ output.docx
```

## 步骤 5：测试文档

确保输出的文档可以正常打开。

## 常见错误

| 错误 | 原因 | 解决方法 |
|:-----|:-----|:---------|
| XML 解析错误 | 标签未闭合 | 检查所有标签是否配对 |
| 文档打不开 | 结构损坏 | 从步骤 1 重新开始 |
| 样式丢失 | 引用了不存在的样式 | 检查 styles.xml |

~/.claude/skills/smart-yapi/
├── SKILL.md              # 主文件：执行步骤 + 代码生成规范
└── yapi_fetcher.py       # Python 脚本：自动登录 YAPI 并获取接口数据

---
name: smart-yapi
description: 解析 YAPI 接口文档生成 Kotlin API 接口和 Bean 类。当用户提供 YAPI URL 或说"生成接口"、"解析yapi"、"yapi转kotlin"时触发。
allowed-tools: Read, Write, Edit, Glob, Grep, Bash(python:*)
---

# Smart YAPI - 解析 YAPI 文档生成接口

## 执行步骤

### 1. 使用 Python 脚本获取接口数据

```bash
python3 .claude/skills/smart-yapi/yapi_fetcher.py "<YAPI_URL>"
```

脚本会自动登录并返回 JSON 格式的接口数据，包含：
- title: 接口名称
- path: 接口路径
- method: 请求方法
- req_body_schema: 请求参数 JSON Schema
- res_body_schema: 返回数据 JSON Schema

### 2. 解析 JSON Schema 生成代码

根据脚本输出的 JSON 数据：
1. 检查是否已存在相关的 ReqBean/ResBean（使用 Glob/Grep）
2. 生成 API 接口定义
3. 生成必要的 Bean 类

## 项目文件位置

- **API 接口文件**: `component_io/src/main/java/com/example/component_io/api/`
- **Bean 类文件**: `component_io/src/main/java/com/example/component_io/bean/`

## 代码生成规范

### API 接口格式

```kotlin
/**
 * 接口描述
 * @param requestBody 参数说明
 */
@POST("/api/path")
suspend fun requestXxx(@Body requestBody: XxxReqBean): BaseBean<XxxResBean>
```

### Bean 类格式

```kotlin
package com.example.component_io.bean

import java.io.Serializable

/**
 * 类描述
 */
class XxxBean : Serializable {
    /**
     * 字段描述
     */
    var field1: String? = null
    /**
     * 字段描述
     */
    var field2: Int? = null

    /**
     * 嵌套类描述
     */
    class InnerBean : Serializable {
        var innerField: String? = null
    }
}
```

### 命名规范

- 方法名: `request` + 功能描述（驼峰）
- 请求 Bean: 功能描述 + `ReqBean`
- 响应 Bean: 功能描述 + `ResBean`
- 嵌套类: 描述性名称 + `Bean`

### 类型映射

| JSON Schema 类型 | Kotlin 类型 |
|-----------------|-------------|
| string | String? |
| integer | Int? |
| number | Double? |
| boolean | Boolean? |
| array | List\<T\>? |
| object | 生成嵌套 Bean 类 |

### 注意事项

1. **Bean 复用策略**：
   - 字段名相同 **且** 字段含义/注释相同 -> 可以复用已有 Bean
   - 字段名相同 **但** 字段含义/注释不同 -> 创建新的独立 Bean
   - 复用前需读取已有 Bean 文件，对比字段和注释
2. 如果 API 接口文件中已有未完成的接口定义，直接补全
3. 必须字段在注释中标注 `(必须)`
4. 分页响应通常包含：totalCount、totalPage、currentPage、pageSize、data、finished
5. 简单的返回类型直接使用 `BaseBean<Int>`、`BaseBean<String>` 等
6. 无请求参数的接口使用 `RequestEmptyBean`

#!/usr/bin/env python3
"""
YAPI 接口数据提取脚本
直接通过 YAPI API 获取接口详情，输出 JSON 格式数据
"""

import json
import re
import sys
import requests

# 通过环境变量或配置文件管理凭证（不要硬编码！）
YAPI_BASE_URL = "http://yapi.your-company.com:3000"
YAPI_EMAIL = "your-email@company.com"
YAPI_PASSWORD = "your-password"


def login(session: requests.Session) -> bool:
    """登录 YAPI"""
    resp = session.post(
        f"{YAPI_BASE_URL}/api/user/login",
        json={"email": YAPI_EMAIL, "password": YAPI_PASSWORD}
    )
    data = resp.json()
    return data.get("errcode") == 0


def parse_url(url: str) -> tuple[str, str]:
    """从 URL 解析 project_id 和 interface_id"""
    # http://yapi.your-company.com:3000/project/123/interface/api/456
    match = re.search(r'/project/(\d+)/interface/api/(\d+)', url)
    if match:
        return match.group(1), match.group(2)
    raise ValueError(f"无法解析 URL: {url}")


def get_interface_detail(session: requests.Session, interface_id: str) -> dict:
    """获取接口详情"""
    resp = session.get(
        f"{YAPI_BASE_URL}/api/interface/get",
        params={"id": interface_id}
    )
    data = resp.json()
    if data.get("errcode") != 0:
        raise Exception(f"获取接口详情失败: {data.get('errmsg')}")
    return data.get("data", {})


def format_output(interface_data: dict) -> dict:
    """格式化输出数据"""
    req_body_other = interface_data.get("req_body_other", "")
    req_body = {}
    if req_body_other:
        try:
            req_body = json.loads(req_body_other)
        except json.JSONDecodeError:
            pass

    res_body = interface_data.get("res_body", "")
    response = {}
    if res_body:
        try:
            response = json.loads(res_body)
        except json.JSONDecodeError:
            pass

    return {
        "title": interface_data.get("title", ""),
        "path": interface_data.get("path", ""),
        "method": interface_data.get("method", "POST"),
        "desc": interface_data.get("desc", ""),
        "req_headers": interface_data.get("req_headers", []),
        "req_body_type": interface_data.get("req_body_type", ""),
        "req_body_schema": req_body,
        "res_body_type": interface_data.get("res_body_type", ""),
        "res_body_schema": response,
    }


def main():
    if len(sys.argv) < 2:
        print("用法: python yapi_fetcher.py <YAPI_URL>", file=sys.stderr)
        sys.exit(1)

    url = sys.argv[1]

    try:
        project_id, interface_id = parse_url(url)
    except ValueError as e:
        print(str(e), file=sys.stderr)
        sys.exit(1)

    session = requests.Session()

    if not login(session):
        print("登录失败", file=sys.stderr)
        sys.exit(1)

    try:
        interface_data = get_interface_detail(session, interface_id)
        output = format_output(interface_data)
        print(json.dumps(output, ensure_ascii=False, indent=2))
    except Exception as e:
        print(f"获取接口数据失败: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()

你：帮我解析这个接口 http://yapi.your-company.com:3000/project/123/interface/api/456
Claude：[自动执行 yapi_fetcher.py 获取接口数据]
      [检查已有 Bean 类是否可复用]
      [生成 API 接口定义和 Bean 类]
      [写入对应文件]

monorepo/
├── .claude/skills/              # 根级 Skills（所有人都能用）
│   └── commit-helper/
├── packages/
│   ├── frontend/
│   │   └── .claude/skills/      # 前端专用 Skills
│   │       └── react-component/
│   └── backend/
│       └── .claude/skills/      # 后端专用 Skills
│           └── api-generator/

my-marketplace/
├── .claude-plugin
├── skills/
│   ├── skill-1/
│   │   └── SKILL.md
│   └── skill-2/
│       └── SKILL.md
└── README.md

开发流程：
1. 在真实任务中观察 Claude 的表现
2. 识别它经常需要重复指导的地方
3. 针对这些具体问题创建 Skill
4. 用真实场景测试和迭代

- SKILL.md 保持在 500 行以内
- 详细内容放到 references/
- 脚本放到 scripts/
- 模板放到 assets/
- 如果内容很少同时使用，拆分到不同文件减少 Token 消耗

# 差：太模糊
description: 帮助处理代码

# 好：具体 + 触发词 + 说明何时用
description: 生成符合 Conventional Commits 规范的 Git 提交信息。当用户说"提交代码"、"commit"、"写提交信息"时使用。

监控和迭代：
1. 观察 Claude 如何使用你的 Skill
2. 注意意外的使用模式或过度依赖某些内容
3. 让 Claude 自我反思失败案例
4. 把成功的模式固化到 Skill 中

# 只读分析
allowed-tools: Read, Grep, Glob

# 需要修改时才加
allowed-tools: Read, Write, Edit

# Git 操作
allowed-tools: Read, Bash(git:*)

## 工作流程

1. **验证前置条件**
   - 检查必要文件存在
   - 确认用户权限

2. **执行操作**
   - 步骤清晰
   - 每步都可验证

3. **验证结果**
   - 确认操作成功
   - 提供回滚方案

4. **敏感操作需确认**
   - 展示将要执行的命令
   - 等待用户确认