06e - Skill 设计模式与排错

用户 Prompt："帮我创建一个新的 API 端点，包含测试和文档"
    │
    ├─→ [api-design Skill]      → 生成 API schema 和路由代码
    ├─→ [test-generation Skill] → 根据 API 生成测试用例
    └─→ [doc-generation Skill]  → 根据 API 生成 OpenAPI 文档

.claude/skills/
├── api-design/
│   └── SKILL.md          # 负责 API 路由和控制器
├── test-generation/
│   └── SKILL.md          # 负责测试代码生成
└── doc-generation/
    └── SKILL.md          # 负责 API 文档生成

---
name: api-design
description: Design and generate REST/GraphQL API endpoints including
  route definitions, controllers, validation middleware, and error handling.
  Use when creating new API endpoints or modifying existing API routes.
  Does NOT handle tests or documentation - those are separate skills.
---
 
# API 设计指令
 
## 职责范围
- REST 端点设计（路由、HTTP 方法、状态码）
- 请求/响应 schema 定义
- 验证中间件生成
- 错误处理模式
 
## 不在职责范围内
- 测试代码（由 test-generation Skill 处理）
- API 文档（由 doc-generation Skill 处理）

[data-modeling Skill] → 生成数据模型
        ↓
[migration-gen Skill] → 根据模型生成迁移文件
        ↓
[seed-data Skill]     → 根据模型生成种子数据

---
name: migration-gen
description: Generate database migration files from data models.
  Use AFTER data models have been defined. Supports Prisma, Drizzle,
  and TypeORM. Requires existing schema files as input.
---
 
# 数据库迁移生成指令
 
## 前置条件
- 数据模型已定义（通常由 data-modeling Skill 完成）
- schema 文件已存在于项目中
 
## 工作流
1. 读取现有 schema/model 文件
2. 检测 ORM 类型（Prisma/Drizzle/TypeORM）
3. 生成迁移文件
4. 添加回滚逻辑

---
name: full-stack-feature
description: Orchestrate the creation of a complete full-stack feature
  including API, frontend component, tests, and documentation.
  Use when building a new feature end-to-end.
---
 
# 全栈功能编排指令
 
## 执行顺序
1. 使用 api-design Skill 创建后端 API
2. 使用 component-gen Skill 创建前端组件
3. 使用 test-generation Skill 生成测试
4. 使用 doc-generation Skill 更新文档
 
## 协调规则
- 每步完成后验证输出再进入下一步
- 如果某步失败，停止并报告，不要继续
- 保持各步骤的命名和路径一致性

.claude/skills/code-review/
├── SKILL.md              # 通用审查流程（不变）
├── config/
│   ├── defaults.md       # 默认配置
│   └── overrides.md      # 项目特定覆盖（可选）
└── checklists/
    ├── security.md       # 安全审查清单
    ├── performance.md    # 性能审查清单
    └── accessibility.md  # 无障碍审查清单

---
name: code-review
description: Perform structured code reviews with configurable checklists
  for security, performance, and accessibility. Use when reviewing PRs,
  commits, or code changes.
---
 
# 代码审查指令
 
## 配置
- 默认配置：[defaults.md](config/defaults.md)
- 项目覆盖：[overrides.md](config/overrides.md)（如果存在则优先）
 
## 审查流程
1. 加载配置（项目覆盖 > 默认配置）
2. 根据文件类型选择对应清单
3. 逐项检查并记录发现
4. 生成审查报告

# 默认审查配置
 
## 语言和框架
- 主语言：TypeScript
- 框架：React + Next.js
- 测试框架：Vitest
 
## 审查重点
- 安全：启用（见 checklists/security.md）
- 性能：启用（见 checklists/performance.md）
- 无障碍：启用（见 checklists/accessibility.md）
 
## 严格度
- 安全问题：必须修复（blocker）
- 性能问题：建议修复（warning）
- 风格问题：可选修复（info）

# 项目覆盖配置（后端 API 项目）
 
## 语言和框架
- 主语言：Python
- 框架：FastAPI
- 测试框架：Pytest
 
## 审查重点
- 无障碍：禁用（后端项目不需要）
 
## 额外检查
- SQL 注入防护：启用
- API 速率限制：启用

---
name: test-gen
description: Generate tests for the current project. Automatically detects
  testing framework (Jest/Vitest/Pytest/Go testing) and adapts patterns.
  Use when creating unit tests, integration tests, or E2E tests.
---
 
# 测试生成指令
 
## 框架检测规则
1. 检查 package.json 中的 devDependencies：
   - 包含 vitest → 使用 Vitest 模式
   - 包含 jest → 使用 Jest 模式
   - 包含 @playwright/test → 使用 Playwright 模式
2. 检查 pyproject.toml 或 setup.cfg：
   - 包含 pytest → 使用 Pytest 模式
3. 检查 go.mod：
   - 存在 → 使用 Go testing 模式
 
## 各框架模式
 
### Vitest 模式
- 文件命名：`*.test.ts` 或 `*.spec.ts`
- 导入：`import { describe, it, expect } from 'vitest'`
- 运行命令：`npx vitest run`
 
### Jest 模式
- 文件命名：`*.test.ts` 或 `*.test.js`
- 导入：无需显式导入（全局）
- 运行命令：`npx jest`
 
### Pytest 模式
- 文件命名：`test_*.py`
- 导入：`import pytest`
- 运行命令：`pytest -v`

~/.claude/skills/code-style/          # 全局默认（组织级）
    └── SKILL.md                      # 通用编码规范

项目/.claude/skills/code-style/       # 项目覆盖
    └── SKILL.md                      # 项目特定规范（优先级更高）

第 1 阶段：发现（Discovery）
  → Agent 启动时只加载所有 Skill 的 name + description
  → 占用极少上下文（每个 Skill 约 50-100 tokens）

第 2 阶段：激活（Activation）
  → 当用户请求匹配某个 Skill 的 description 时
  → Agent 读取完整的 SKILL.md 到上下文中

第 3 阶段：执行（Execution）
  → Agent 按 SKILL.md 指令执行
  → 按需加载 references/、scripts/ 等辅助文件

# ❌ 模糊的 description——容易误触发
---
name: deploy
description: Help with deployment.
---
 
# ✅ 精准的 description——明确触发条件和排除条件
---
name: deploy-vercel
description: Deploy Next.js applications to Vercel. Handles environment
  variables, build configuration, domain setup, and preview deployments.
  Use when deploying to Vercel or configuring Vercel projects.
  Do NOT use for AWS, Docker, or Kubernetes deployments.
---

#!/bin/bash
# .claude/hooks/activate-skills.sh
# 检测 prompt 中的关键词，强制激活对应 Skill
 
INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty')
 
# 部署相关关键词 → 激活 deploy Skill
if echo "$PROMPT" | grep -qiE '(deploy|部署|上线|发布)'; then
  echo "🚀 INSTRUCTION: Use Skill(deploy-vercel) to handle this deployment request."
fi
 
# 数据库相关关键词 → 激活 migration Skill
if echo "$PROMPT" | grep -qiE '(migration|迁移|schema|数据库)'; then
  echo "🗄️ INSTRUCTION: Use Skill(migration-gen) to handle this database task."
fi
 
# 测试相关关键词 → 激活 test-gen Skill
if echo "$PROMPT" | grep -qiE '(test|测试|spec|断言)'; then
  echo "🧪 INSTRUCTION: Use Skill(test-gen) to handle this testing task."
fi

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/activate-skills.sh"
          }
        ]
      }
    ]
  }
}

# .kiro/steering/skill-routing.md
---
inclusion: always
---
 
# Skill 路由规则
 
当处理以下类型的任务时，请优先查找并使用对应的 Skill：
 
- 部署相关任务 → 查找 deploy 相关 Skill
- 数据库变更 → 查找 migration 相关 Skill
- 代码审查 → 查找 code-review 相关 Skill
- 测试生成 → 查找 test-gen 相关 Skill
 
在执行任何专业任务前，先检查 .kiro/skills/ 目录中是否有匹配的 Skill。

---
name: react-patterns
description: Apply React best practices and component patterns.
  Activates when working with .tsx, .jsx files or React components.
  Covers hooks, state management, performance optimization, and
  accessibility patterns for React applications.
---

用户发出请求
    │
    ├─ 请求是否匹配某个 Skill 的 description？
    │   ├─ 是 → Skill 自动激活（理想情况）
    │   └─ 否 → Skill 不激活
    │
    ├─ Skill 自动激活是否可靠？
    │   ├─ 是 → 使用 description 路由（方式一）
    │   └─ 否 → 添加 Hook 强制激活（方式二）
    │
    └─ 是否需要始终提醒 Agent 检查 Skills？
        ├─ 是 → 添加 Steering 规则（方式三）
        └─ 否 → 仅依赖 description

.claude/skills/
├── orchestrators/                    # 编排层（组合模式）
│   ├── new-feature/
│   │   └── SKILL.md                 # 编排新功能的完整流程
│   └── bug-fix/
│       └── SKILL.md                 # 编排 bug 修复流程
│
├── generators/                       # 生成层（参数化模式）
│   ├── api-gen/
│   │   ├── SKILL.md                 # 通用 API 生成逻辑
│   │   └── config/
│   │       ├── rest.md              # REST 配置
│   │       └── graphql.md           # GraphQL 配置
│   ├── component-gen/
│   │   ├── SKILL.md                 # 通用组件生成逻辑
│   │   └── config/
│   │       ├── react.md             # React 配置
│   │       └── vue.md               # Vue 配置
│   └── test-gen/
│       ├── SKILL.md                 # 通用测试生成逻辑
│       └── config/
│           ├── vitest.md            # Vitest 配置
│           └── pytest.md            # Pytest 配置
│
├── reviewers/                        # 审查层（条件激活模式）
│   ├── security-review/
│   │   └── SKILL.md                 # 安全审查（仅在涉及认证/权限时激活）
│   ├── perf-review/
│   │   └── SKILL.md                 # 性能审查（仅在涉及数据库/API时激活）
│   └── a11y-review/
│       └── SKILL.md                 # 无障碍审查（仅在涉及 UI 时激活）
│
└── utilities/                        # 工具层
    ├── git-workflow/
    │   └── SKILL.md                 # Git 操作规范
    └── env-setup/
        └── SKILL.md                 # 环境配置指南

---
name: new-feature
description: Orchestrate the creation of a new feature end-to-end.
  Coordinates API generation, frontend components, tests, and reviews.
  Use when starting a new feature or user story implementation.
---
 
# 新功能编排指令
 
## 执行流程
1. **需求分析**：理解功能需求，确定涉及的层（API/前端/数据库）
2. **API 层**：如果需要后端，使用 api-gen Skill 生成 API
3. **前端层**：如果需要 UI，使用 component-gen Skill 生成组件
4. **测试层**：使用 test-gen Skill 为新代码生成测试
5. **审查层**：根据涉及的领域，触发对应的审查 Skill
6. **收尾**：更新文档，提交代码
 
## 协调规则
- 每步完成后确认无错误再继续
- 保持命名一致性（API 路由名 = 组件名 = 测试文件名）
- 如果某步需要用户决策，停下来询问

步骤 1：验证 Skill 是否被识别
  → 在 Claude Code 中输入："列出所有可用的 Skills"
  → 确认目标 Skill 出现在列表中

步骤 2：检查 description 质量
  → description 是否包含用户请求中的关键词？
  → description 是否足够具体？（"帮助处理文件"太模糊）
  → description 是否包含触发场景说明？

步骤 3：检查 YAML frontmatter 格式
  → 确认 --- 分隔符正确
  → 确认 name 和 description 字段存在
  → 确认 YAML 语法无误（缩进、引号）

步骤 4：如果以上都正常，使用 Hook 强制激活
  → 创建 UserPromptSubmit Hook 脚本
  → 检测关键词并输出激活指令

#!/bin/bash
# .claude/hooks/skill-reminder.sh
# 在每次 prompt 提交时提醒 Agent 检查 Skills
 
INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty')
 
# 始终提醒（轻量级方案）
echo "💡 Reminder: Check available skills before proceeding."
 
# 或者：关键词匹配后精准提醒（推荐）
if echo "$PROMPT" | grep -qiE '(deploy|test|review|generate|create)'; then
  echo "💡 INSTRUCTION: Check if any installed Skill matches this request before proceeding manually."
fi

步骤 1：审查 description 是否过于宽泛
  → "帮助处理代码" 会在几乎所有编码任务中触发
  → 改为 "帮助处理 Python 异步代码的错误处理"

步骤 2：添加否定条件
  → 在 description 末尾添加 "Do NOT use for..."
  → 明确列出不适用的场景

步骤 3：检查是否与其他 Skill 的 description 重叠
  → 列出所有 Skill 的 description
  → 确认没有两个 Skill 覆盖相同的关键词

# ❌ 错误 1：缺少 --- 分隔符
name: my-skill
description: Does something
 
# ✅ 修复：添加 --- 分隔符
---
name: my-skill
description: Does something
---
 
# ❌ 错误 2：description 中包含未转义的特殊字符
---
name: my-skill
description: Handle "special" cases & edge cases
---
 
# ✅ 修复：用引号包裹含特殊字符的值
---
name: my-skill
description: "Handle 'special' cases and edge cases"
---
 
# ❌ 错误 3：多行 description 缩进错误
---
name: my-skill
description: This is a long description
that continues on the next line
---
 
# ✅ 修复：使用 YAML 多行语法
---
name: my-skill
description: >
  This is a long description
  that continues on the next line.
---
 
# ❌ 错误 4：name 包含大写字母或空格
---
name: My Skill
description: Does something
---
 
# ✅ 修复：name 只用小写字母、数字和连字符
---
name: my-skill
description: Does something
---

步骤 1：估算 SKILL.md 的 token 数
  → 粗略估算：英文约 1 token/词，中文约 1.5-2 tokens/字
  → SKILL.md 建议控制在 2000-3000 tokens 以内

步骤 2：检查辅助文件是否被不必要地全部加载
  → SKILL.md 中是否有"加载以下所有文件"的指令？
  → 改为"根据需要加载对应文件"

步骤 3：检查是否有多个 Skill 同时被激活
  → 多个 Skill 同时加载会叠加上下文占用
  → 优化 description 减少不必要的并行激活

# 瘦身前：所有内容塞在 SKILL.md 中（~5000 tokens）
---
name: code-review
description: Perform code reviews.
---
# 代码审查
## 安全检查清单（800 tokens）
## 性能检查清单（600 tokens）
## 无障碍检查清单（500 tokens）
## 代码风格清单（400 tokens）
## 审查报告模板（300 tokens）
...
 
# 瘦身后：SKILL.md 只保留核心流程（~1500 tokens）
---
name: code-review
description: Perform code reviews with security, performance,
  and accessibility checklists.
---
# 代码审查
 
## 审查流程
1. 确定审查范围和重点
2. 根据需要加载对应清单：
   - 安全相关 → 见 [security.md](checklists/security.md)
   - 性能相关 → 见 [performance.md](checklists/performance.md)
   - 无障碍相关 → 见 [a11y.md](checklists/a11y.md)
3. 逐项检查
4. 生成报告（模板见 [report.md](templates/report.md)）

# 步骤 1：检查安装位置
ls -la .claude/skills/          # 项目级
ls -la ~/.claude/skills/        # 全局级
 
# 步骤 2：检查 settings.json 中的 enabledPlugins
cat .claude/settings.json | jq '.enabledPlugins'
 
# 步骤 3：如果插件未启用，手动启用
claude plugin enable [plugin-name]@[marketplace]
 
# 步骤 4：清除缓存（如果安装了旧版本）
rm -rf ~/.claude/plugins/cache/[marketplace]
claude plugin marketplace update [marketplace]

// .claude/settings.json
{
  "enabledPlugins": {
    "my-skill@local": true,      // 确保值为 true
    "remotion@marketplace": true
  }
}

# 1. 检查脚本是否有执行权限
chmod +x .claude/hooks/my-hook.sh
 
# 2. 检查脚本是否能独立运行
echo '{"prompt":"test deploy"}' | bash .claude/hooks/my-hook.sh
 
# 3. 检查 jq 是否安装（如果脚本使用 jq）
which jq || echo "jq not installed!"
 
# 4. 检查 settings.json 中 Hook 配置格式
cat .claude/settings.json | jq '.hooks'
 
# 5. 检查 Hook 事件类型是否正确
# 常见事件：UserPromptSubmit, PostToolUse, PreToolUse

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/activate-skills.sh"
          }
        ]
      }
    ]
  }
}

# ❌ 使用绝对路径（不可移植）
详见 [安全清单](/Users/me/project/.claude/skills/review/security.md)
 
# ❌ 路径相对于项目根目录（Skill 不知道项目根在哪）
详见 [安全清单](.claude/skills/review/security.md)
 
# ✅ 路径相对于 SKILL.md 所在目录
详见 [安全清单](checklists/security.md)
 
# ✅ 同级目录引用
详见 [配置说明](./config.md)

Skill 不工作？
    │
    ├─ Skill 出现在可用列表中吗？
    │   ├─ 否 → 检查 YAML frontmatter 格式（问题三）
    │   │       检查安装位置和启用状态（问题六）
    │   └─ 是 ↓
    │
    ├─ Skill 被激活了吗？
    │   ├─ 否 → 优化 description 关键词（问题一）
    │   │       添加 Hook 强制激活（问题一）
    │   └─ 是 ↓
    │
    ├─ Skill 激活后行为正确吗？
    │   ├─ 被错误触发 → 收窄 description（问题二）
    │   ├─ 加载后质量下降 → 瘦身 SKILL.md（问题四）
    │   ├─ 辅助文件加载失败 → 检查路径（问题八）
    │   └─ 跨平台不一致 → 检查平台差异（问题五）
    │
    └─ Hook 辅助不工作？
        → 检查权限和配置（问题七）

我的 Skill "[Skill 名称]" 遇到了问题：

## 问题描述
- 预期行为：[Skill 应该做什么]
- 实际行为：[Skill 实际做了什么/没做什么]
- 平台：[Claude Code / Kiro / Cursor]

## 已尝试的排查
- [ ] 确认 Skill 出现在可用列表中
- [ ] 检查 YAML frontmatter 格式
- [ ] 测试 description 关键词匹配
- [ ] 检查文件路径引用

## SKILL.md 内容

## 目录结构

请帮我诊断问题并提供修复方案。

┌─────────────────────────────────────────────────────┐
│  Steering（始终生效的约束和指导）                       │
│  "做什么"和"不做什么"的规则                            │
│  例：代码风格、安全约束、命名规范                       │
│  加载时机：始终 / 文件路径匹配时                        │
├─────────────────────────────────────────────────────┤
│  Skills（按需加载的专业能力）                           │
│  "怎么做"的详细指令和资源                              │
│  例：部署流程、测试生成、代码审查                       │
│  加载时机：AI 判断相关时 / Hook 触发时                  │
├─────────────────────────────────────────────────────┤
│  Hooks（事件驱动的自动化）                             │
│  "何时做"的触发机制                                    │
│  例：文件保存时格式化、提交前检查、Skill 激活辅助        │
│  加载时机：特定事件发生时（确定性触发）                  │
└─────────────────────────────────────────────────────┘

---
inclusion: always
---
# 数据库安全规则
- 禁止在迁移中使用 DROP TABLE（除非有明确的备份确认）
- 所有迁移必须包含回滚逻辑
- 大表变更必须使用在线 DDL（pt-online-schema-change 或等效工具）

---
name: migration-gen
description: Generate safe database migration files with rollback logic.
  Use when creating schema changes, adding columns, or modifying tables.
---
# 迁移生成指令
## 流程
1. 分析 schema 变更需求
2. 生成迁移文件（遵循 db-safety Steering 规则）
3. 生成对应的回滚文件
4. 运行安全检查清单

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": { "tool": "write_file", "path": "**/migrations/**" },
        "hooks": [
          {
            "type": "command",
            "command": "bash .kiro/hooks/check-migration-safety.sh"
          }
        ]
      }
    ]
  }
}

---
name: research
description: Help with research tasks.
---

---
name: research
description: Conduct thorough research with source verification.
  Fetch actual content from URLs, verify claims against primary sources,
  and provide citations. Use when asked to "research", "investigate",
  "study", "verify", or "fact-check" any topic. Do NOT use for
  simple questions that can be answered from training data.
---

✅ "research if Claude Code prefers CLI or MCP tools" → 触发
✅ "帮我调研一下 2026 年的 AI 测试工具" → 触发
❌ "这个 API 怎么用？" → 不触发（正确，这不是研究任务）
⚠️ "study the performance of this function" → 有时触发，有时不触发

#!/bin/bash
# ~/.claude/hooks/auto-research.sh
INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty')
 
if echo "$PROMPT" | grep -qiE '(research|study|investigate|调研|研究|考察)'; then
  echo "🔍 INSTRUCTION: Use Skill(research) to handle this request with source verification."
fi

✅ "research if Claude Code prefers CLI or MCP tools" → 触发（description 匹配）
✅ "study the performance of this function" → 触发（Hook 保底）
✅ "帮我调研一下 2026 年的 AI 测试工具" → 触发（Hook 中文关键词）
❌ "这个 API 怎么用？" → 不触发（正确）