这个 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 组件 Skill | SKILL.md + scripts/ + resources/template/ | 完整包:脚本验证 + 模板驱动 |
| API 端点 Skill | SKILL.md + resources/config/ | 配置外部化 |
| Git 提交 Skill | 仅 SKILL.md | 最简结构 |
| 安全审计 Skill | SKILL.md + references/ + resources/examples/ | 参考文档驱动审查 |













请登录后查看评论内容