4.3.3 实战:创建一个 API 端点生成 Skill

这个 Skill 相对简单,不需要辅助脚本,只需一个 SKILL.md 加一份配置文件:

.claude/skills/api-endpoint/
├── SKILL.md                 # 核心指令
└── resources/
  └── config/
    └── response-format.json   # API 统一返回格式定义

创建 .claude/skills/api-endpoint/SKILL.md:

---
name: api-endpoint-generator
version: 1.0
description: 为指定的数据模型生成标准的 CRUD API 端点
trigger: ["创建API", "生成端点", "新建接口"]
---

# RESTful API 端点生成器

## 输入参数
- modelName(必填):数据模型名称(如 "bookmark"、"tag")
- fields(必填):模型字段列表
- operations(可选,默认全部):需要的操作(create/read/update/delete/list)

## 执行步骤

1. 在 `src/app/api/{modelName}s/` 目录下创建 `route.ts`

2. 实现以下端点:
   - GET /api/{modelName}s → 获取列表(支持分页、搜索)
   - POST /api/{modelName}s → 创建
   - GET /api/{modelName}s/[id] → 获取单个
   - PUT /api/{modelName}s/[id] → 更新
   - DELETE /api/{modelName}s/[id] → 删除

3. 代码规范:
   - 使用 Prisma Client 操作数据库
   - 统一返回格式参考 `resources/config/response-format.json`
   - 包含输入验证
   - 包含错误处理(try-catch)

4. 创建完成后,列出所有 API 端点的 URL 和用法

同时创建 .claude/skills/api-endpoint/resources/config/response-format.json:

{
  "success_response": {
   "success": true,
   "data": "<返回数据>"
  },
  "error_response": {
   "success": false,
   "error": "<错误信息>"
  },
  "list_response": {
   "success": true,
   "data": "<数据数组>",
   "pagination": {
     "page": 1,
     "pageSize": 20,
     "total": 100
   }
  }
}

提示:把 API 的返回格式定义抽到 resources/config/ 中,好处是 SKILL.md 更简洁,而且修改格式时只需改 JSON 文件,不用动 Skill 指令。

4.3.4 实战:创建一个 Git 规范化 Skill

Git 规范化 Skill 非常简单,不需要脚本和资源文件,只需一个 SKILL.md 即可。这说明并非所有 Skill 都要用上全套目录 —— 够用就好。

创建 .claude/skills/git-commit/SKILL.md:

---
name: git-commit-standard
version: 1.0
description: 在提交代码时,自动生成符合 Conventional Commits 规范的 commit message
trigger: ["提交代码", "git commit", "生成commit"]
---

# Git 提交规范化

## 执行步骤

1. 运行 `git diff --staged` 查看暂存区的修改
2. 分析修改内容,判断变更类型:
   - feat: 新功能
   - fix: 修复Bug
   - refactor: 重构(不改变功能)
   - style: 样式修改
   - docs: 文档更新
   - test: 测试相关
   - chore: 构建/工具变更

3. 生成 commit message,格式:
   ```
   <type>(<scope>): <description>

   <body>
   ```

4. 显示给用户确认后执行 `git commit`

## 示例
修改了 src/components/BookmarkCard.tsx 中的样式

生成的 message:
​```
style(BookmarkCard): 优化书签卡片的响应式布局

- 调整了移动端下的卡片宽度
- 修复了标签溢出问题
​```

提示:注意对比三个实战 Skill 的复杂度递减关系 —— React 组件 Skill(完整包:SKILL.md + scripts + resources)→ API 端点 Skill(中等:SKILL.md + resources/config)→ Git 提交 Skill(最简:仅 SKILL.md)。根据实际需求选择合适的结构,不必过度设计。

4.3.5 实战:创建一个代码安全审计 Skill(references 实践)

前面三个案例分别展示了 scripts/、resources/、纯 SKILL.md 的用法,这个案例重点展示 references/ 目录 —— 当 Skill 需要 AI 依据特定的标准和规范来执行任务时,把参考文档放入 references/ 是最佳实践。

需求:在提交代码前,让 AI 按照 OWASP 安全清单和团队编码安全规范,对代码进行安全审计。

Step 1:创建 Skill 目录结构

$ mkdir -p .claude/skills/security-audit/references
$ mkdir -p .claude/skills/security-audit/resources/examples

完成后的结构:

.claude/skills/security-audit/
├── SKILL.md                    # 审计流程指令
├── references/                  #  参考文档(AI 审计时依据的"法规")
│   ├── owasp-top10-checklist.md     # OWASP Top 10 安全检查清单
│   └── team-security-standards.md   # 团队安全编码规范
└── resources/
   └── examples/
      └── audit-report-sample.md   # 审计报告示例(让 AI 知道输出长什么样)

Step 2:编写 SKILL.md

创建 .claude/skills/security-audit/SKILL.md:

---
name: security-audit
version: 1.0
description: 对指定代码进行安全审计,依据 OWASP Top 10 和团队安全规范输出审计报告
trigger: ["安全审计", "security audit", "安全检查", "代码安全"]
---

# 代码安全审计

## 执行步骤

1. 读取用户指定的代码文件或目录
2. 阅读 `references/owasp-top10-checklist.md`,逐项检查代码是否存在对应漏洞
3. 阅读 `references/team-security-standards.md`,检查代码是否符合团队安全规范
4. 按照 `resources/examples/audit-report-sample.md` 的格式,生成安全审计报告
5. 对每个发现的问题:标注严重等级(高危/中危/低危)、给出修复建议和修复代码

## 输出规范
- 使用 Markdown 表格列出所有问题
- 每个问题包含:文件路径、行号、问题描述、严重等级、修复建议
- 最后给出安全评分(0-100)和总结

## 错误处理
- 如果代码量过大,优先审计 API 路由和数据库操作相关的文件
- 如果无法判断是否存在风险,标记为"待人工确认"

Step 3:编写参考文档(references/)

这是本案例的重点。references/ 中的文件不会直接变成输出,而是作为 AI 做判断时的”知识库”。

创建 .claude/skills/security-audit/references/owasp-top10-checklist.md:

# OWASP Top 10 安全检查清单

## 1. 注入攻击(Injection)
- [ ] SQL 查询是否使用参数化查询或 ORM?
- [ ] 是否存在字符串拼接 SQL 的情况?
- [ ] 用户输入是否经过转义和过滤?

## 2. 身份认证失效(Broken Authentication)
- [ ] 密码是否明文存储?(应使用 bcrypt 等加密)
- [ ] 会话令牌是否使用安全的随机数生成?
- [ ] 是否有登录失败次数限制?

## 3. 敏感数据泄露(Sensitive Data Exposure)
- [ ] API 密钥、数据库密码是否硬编码在代码中?
- [ ] 敏感数据是否通过 HTTPS 传输?
- [ ] 日志中是否记录了敏感信息?

## 4. XSS 跨站脚本攻击
- [ ] 用户输入是否在渲染前经过转义?
- [ ] 是否使用 dangerouslySetInnerHTML 等危险 API?
- [ ] CSP(Content Security Policy)头是否设置?

## 5. 安全配置错误
- [ ] 是否关闭了调试模式?
- [ ] 错误页面是否暴露了堆栈信息?
- [ ] 默认账户密码是否已修改?

(后续 6-10 条按同样格式补充)

创建 .claude/skills/security-audit/references/team-security-standards.md:

# 团队安全编码规范

## 强制规则(违反即为高危)
1. 禁止在代码中硬编码任何密钥、密码、令牌,必须使用环境变量
2. 所有数据库操作必须通过 ORM(Prisma),禁止直接写 SQL
3. 所有用户输入必须在服务端验证,不能只依赖前端验证
4. API 路由必须有权限校验,不允许裸接口

## 建议规则(违反为中危)
1. 文件上传功能必须限制文件类型和大小
2. 敏感操作(删除、修改密码等)需要二次确认
3. 分页查询必须限制 pageSize 最大值,防止数据库压力攻击
4. 错误响应不应包含内部实现细节

Step 4:编写输出示例(resources/examples/)

创建 .claude/skills/security-audit/resources/examples/audit-report-sample.md:

# 安全审计报告

**审计范围**:src/app/api/
**审计时间**:2026-04-30
**审计依据**:OWASP Top 10 + 团队安全规范

## 发现问题

| # | 文件 | 行号 | 问题描述 | 等级 | 修复建议 |
|---|------|------|---------|------|---------|
| 1 | src/app/api/users/route.ts | 23 | SQL 字符串拼接,存在注入风险 |  高危 | 改用 Prisma 参数化查询 |
| 2 | src/lib/auth.ts | 45 | API 密钥硬编码 |  高危 | 移至 .env 环境变量 |
| 3 | src/app/api/upload/route.ts | 12 | 文件上传未限制类型 |  中危 | 添加 MIME 类型白名单 |

## 安全评分:65/100

## 总结
发现 2 个高危、1 个中危问题。建议优先修复高危问题后再上线。

Step 5:使用 Skill

> 请使用安全审计 Skill,对 src/app/api/ 目录下的所有文件进行安全检查。

AI 会先读取 references/ 中的两份参考文档作为审计标准,然后逐一检查代码,最后按照 resources/examples/ 中的示例格式输出审计报告。

提示:注意 references/ 的价值 —— 如果不提供参考文档,AI 会按照自己的通用知识来审计,可能遗漏团队特有的安全要求。有了 references/,审计标准就变得确定、可控、可迭代 —— 团队安全规范更新了?改一下 references/team-security-standards.md 就行。

现在回顾四个案例,每个都突出了不同的 Skill 目录组件:

案例核心组件教学重点
React 组件 SkillSKILL.md + scripts/ + resources/template/完整包:脚本验证 + 模板驱动
API 端点 SkillSKILL.md + resources/config/配置外部化
Git 提交 Skill仅 SKILL.md最简结构
安全审计 SkillSKILL.md + references/ + resources/examples/参考文档驱动审查
© 版权声明
THE END
喜欢就支持一下吧
点赞12 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容