# 个人级Skill（全局可用）
~/.claude/skills/my-skill/SKILL.md

# 项目级Skill（仅当前项目可用）
your-project/.claude/skills/my-skill/SKILL.md

---
[YAML Frontmatter - 元数据配置区]
---

[Markdown Body - 指令内容区]

---
name: my-skill-name          # 必填：Skill唯一标识，用kebab-case
description: 一句话描述Skill功能  # 必填：用于Skill列表展示和关键词匹配
triggers:                     # 可选：触发条件，控制自动激活
  - 关键词1
  - 关键词2
user_invocable: true          # 可选：是否支持 /skillname 手动调用，默认true
disabled: false               # 可选：是否禁用，默认false
---

# Skill名称

## 触发条件
明确列出什么情况下应该使用此Skill。

## 输入规范
描述Skill期望接收什么输入（文件路径、文本内容、参数等）。

## 执行步骤
1. 第一步：具体操作
2. 第二步：具体操作
3. ...

## 输出格式
描述Skill应该生成什么样的输出。

## 约束与边界
- 本Skill不处理XXX
- 当遇到XXX时，提示用户而非自行决定

## 示例
提供至少一个完整的输入→输出示例。

# 在你的测试项目中创建Skill目录
mkdir -p .claude/skills/api-doc-generator
cd .claude/skills/api-doc-generator

---
name: api-doc-generator
description: 分析项目中的API路由定义，生成标准RESTful API文档。当用户提到"生成API文档"、"API文档"、"接口文档"、"写API文档"时触发。
triggers:
  - API文档
  - 接口文档
  - 生成文档
  - api documentation
  - openapi
  - swagger
user_invocable: true
---

# API文档生成器

## 何时使用
当用户要求为项目生成API文档、接口文档，或提到OpenAPI/Swagger规范时，激活此Skill。

## 输入
- 项目路径（默认为当前工作目录）
- 目标框架（自动检测或由用户指定）
- 输出格式：Markdown（默认）或OpenAPI 3.0 YAML

## 执行步骤

### 第一步：识别框架
读取项目的package.json、requirements.txt、go.mod或其他依赖文件，判断后端框架：

| 框架 | 特征文件 | 路由定义模式 |
|------|---------|------------|
| Express.js | package.json含"express" | app.get/post/put/delete |
| FastAPI | requirements.txt含"fastapi" | @app.get/post装饰器 |
| Spring Boot | pom.xml/build.gradle | @GetMapping/@PostMapping |
| Django REST | settings.py含"rest_framework" | urlpatterns列表 |
| Gin | go.mod含"gin-gonic" | r.GET/POST/PUT/DELETE |
| Flask | requirements.txt含"flask" | @app.route装饰器 |

### 第二步：扫描路由文件
使用Grep工具搜索路由定义模式，定位所有包含API端点的文件。

### 第三步：提取端点信息
对每个API端点，提取以下信息：
- HTTP方法（GET/POST/PUT/DELETE/PATCH）
- 路径（如`/api/v1/users/:id`）
- 请求参数（query、path、body）
- 请求体Schema（如果存在）
- 响应格式
- 认证要求（如果可推断）
- 描述/注释

### 第四步：生成文档
按以下格式输出Markdown文档：

```markdown
# API文档

## 概述
- 基础URL：`（推断或使用占位符）`
- 认证方式：`（Bearer Token / API Key / None）`
- 版本：`（从package.json或配置推断）`

## 端点列表

### [方法] 路径

**描述**：端点功能说明

**请求参数**：
| 参数名 | 位置 | 类型 | 必填 | 描述 |
|--------|------|------|------|------|

**请求体**：
（JSON Schema或示例）

**响应**：
| 状态码 | 描述 | Schema |
|--------|------|--------|

**示例**：
（curl命令示例）

### 4.3 添加辅助资源文件

Skill不仅限于SKILL.md，你可以在同一目录下放置辅助文件，Claude Code会在需要时自动加载它们。

创建一个文档模板文件：

```bash
# 在 .claude/skills/api-doc-generator/ 目录下
cat > openapi-template.yaml << 'TEMPLATE'
# OpenAPI 3.0 模板 - 用于生成标准化API文档
openapi: "3.0.3"
info:
  title: "[项目名称]"
  version: "1.0.0"
  description: "[项目描述]"
servers:
  - url: "http://localhost:3000"
    description: "开发环境"
paths:
  # Claude将在此处填充端点
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
TEMPLATE

cat > framework-hints.md << 'HINTS'
# 框架特定提取规则

## Express.js
- 路由文件通常在 `routes/` 或 `src/routes/` 目录
- 中间件 `app.use('/path', router)` 中的路径是前缀
- 参数用 `:paramName` 表示

## FastAPI
- 路由定义在Python文件中用装饰器标注
- `@router.get("/items/{item_id}")` 中的路径参数用花括号
- Pydantic模型定义了请求/响应Schema

## Spring Boot
- `@RestController` 类中的方法即端点
- `@RequestMapping` 在类级别设置前缀
- 方法级注解 `@GetMapping`、`@PostMapping` 等
HINTS

.claude/skills/api-doc-generator/
├── SKILL.md                # 核心指令文件
├── openapi-template.yaml   # OpenAPI模板
└── framework-hints.md      # 框架检测辅助文件

# 1. 进入你的测试项目
cd /path/to/your/test-project

# 2. 确认Skill已就位
ls -la .claude/skills/api-doc-generator/

# 3. 启动Claude Code
claude

# 4. 测试手动激活
> /api-doc-generator

# 5. 测试自动激活（新会话中）
> 帮我生成这个项目的API文档

原因：description和triggers中的关键词与用户消息匹配度不足
解决：扩展triggers列表，在description中加入更多自然语言表达

原因：指令正文过长或结构不清晰，Claude遗漏了部分步骤
解决：精简正文，使用编号列表，每个步骤控制在3-5行以内

原因：SKILL.md正文中没有引用这些文件的指令
解决：在正文中明确提及辅助文件，如"参考openapi-template.yaml模板格式"

## 执行步骤
逐一检查以下每一项：

- [ ] 1. 检查输入验证是否完备
- [ ] 2. 检查错误处理是否覆盖所有边界情况
- [ ] 3. 检查是否有SQL注入风险
- [ ] 4. 检查日志是否包含敏感信息
- [ ] 5. 检查认证授权是否正确

## 执行步骤
1. 收集输入：扫描[目标文件/目录]
2. 解析：从输入中提取[关键信息]
3. 转换：按[模板格式]组织信息
4. 输出：写入[目标文件]
5. 校验：检查输出的完整性和一致性

## 执行阶段

### 阶段1：预处理
- 读取原始输入文件
- 标准化格式
- 输出：normalized.json

### 阶段2：分析
- 基于 normalized.json 进行深度分析
- 提取关键指标
- 输出：analysis-result.md

### 阶段3：报告
- 基于 analysis-result.md 生成最终报告
- 包含图表和摘要
- 输出：final-report.md

## 强制规则
在执行任何代码修改之前，必须通过以下检查：

1. **备份检查**：确认目标文件已备份
2. **影响范围检查**：列出所有受影响的文件
3. **回滚方案**：提供git回滚命令
4. **测试验证**：修改后必须运行完整测试套件

如果任何一项检查失败，停止执行并向用户报告。

## 角色
你是一位拥有15年经验的高级安全工程师，专注于Web应用安全。

## 知识领域
- OWASP Top 10
- 常见漏洞模式（XSS、CSRF、SQL注入、SSRF）
- 安全编码最佳实践
- 威胁建模方法论

## 审查标准
对每个发现的漏洞，按CVSS 3.1评分，分为：
- Critical (9.0-10.0)
- High (7.0-8.9)
- Medium (4.0-6.9)
- Low (0.1-3.9)

.claude/skills/
├── security/
│   ├── sql-injection-scanner/SKILL.md
│   ├── xss-scanner/SKILL.md
│   └── dependency-audit/SKILL.md
├── docs/
│   ├── api-doc-generator/SKILL.md
│   └── changelog-generator/SKILL.md
└── quality/
    ├── code-review/SKILL.md
    └── test-generator/SKILL.md

## 当前环境信息
运行以下命令获取项目状态：
- `git branch --show-current`：当前分支
- `git diff --stat`：未提交的变更
- `cat package.json | grep version`：项目版本

在执行Skill之前，先获取这些信息作为上下文。

# 项目指南

## 安全审查
每次修改认证相关代码时，自动使用 sql-injection-scanner 和 xss-scanner Skill。

## 文档更新
每次添加新API端点后，使用 api-doc-generator 更新文档。

---
name: production-deploy-guard
description: 在部署到生产环境之前执行安全检查清单。仅在用户提到"部署"或"deploy"到"生产"或"production"时激活。
triggers:
  - 部署到生产
  - 生产环境部署
  - deploy production
  - production deploy
---

# 1. 创建独立仓库
mkdir api-doc-generator-skill && cd api-doc-generator-skill

# 2. 复制Skill文件
cp -r /path/to/.claude/skills/api-doc-generator/* .

# 3. 添加README
cat > README.md << 'EOF'
# API文档生成器 - Claude Code Skill

## 安装
```bash
# 克隆到Claude Code skills目录
git clone https://github.com/yourname/api-doc-generator-skill.git \
  ~/.claude/skills/api-doc-generator