06a - 工具到 Skills 的概念层次

┌─────────────────────────────────────────────────────────┐
│                  第 4 层：Subagents                       │
│          独立上下文 · 并行执行 · 任务编排                   │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│   │ 调试专家  │  │ 重构专家  │  │ 安全审查  │  ...         │
│   └────┬─────┘  └────┬─────┘  └────┬─────┘              │
│        │             │             │                     │
├────────┼─────────────┼─────────────┼─────────────────────┤
│                  第 3 层：Skills                          │
│        可复用工作流 · 渐进式加载 · 领域专业知识              │
│   ┌──────────────────────────────────────────┐           │
│   │  SKILL.md + 脚本 + 模板 + 资源文件         │           │
│   └──────────────────┬───────────────────────┘           │
│                      │                                   │
├──────────────────────┼───────────────────────────────────┤
│                  第 2 层：MCP                             │
│        标准化协议 · 外部系统连接 · 按需数据获取              │
│   ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐        │
│   │ GitHub │  │ 数据库  │  │ Slack  │  │ 浏览器  │  ...   │
│   └───┬────┘  └───┬────┘  └───┬────┘  └───┬────┘        │
│       │           │           │           │              │
├───────┼───────────┼───────────┼───────────┼──────────────┤
│                  第 1 层：Tools                           │
│        原子操作 · 始终可用 · 单一职责                       │
│   ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐          │
│   │ Read │ │ Edit │ │ Bash │ │ Grep │ │ Glob │  ...     │
│   └──────┘ └──────┘ └──────┘ └──────┘ └──────┘          │
└─────────────────────────────────────────────────────────┘

请使用以下工具完成任务：
1. 用 Grep 搜索所有包含 [关键词] 的文件
2. 用 Read 读取找到的文件
3. 用 Edit 修改 [具体修改内容]
4. 用 Bash 运行 [验证命令] 确认修改正确

# 添加远程 HTTP Server（如 Notion）
claude mcp add --transport http notion https://mcp.notion.com/mcp
 
# 添加本地 stdio Server（如 PostgreSQL）
claude mcp add --transport stdio postgres \
  --env DATABASE_URL=$DB_URL \
  -- npx -y @bytebase/dbhub

# 在 Claude Code 中查看已连接的 MCP Server
/mcp

请通过 MCP 连接 [服务名称]，完成以下操作：
1. 从 [数据源] 获取 [具体数据]
2. 分析数据并 [处理要求]
3. 将结果 [输出方式]

第 1 级：元数据加载（~100 tokens）
  ├── name: "code-reviewer"
  └── description: "Review code for best practices..."
         ↓ Agent 判断是否相关
第 2 级：完整指令加载（<5K tokens）
  └── SKILL.md 中的详细指令
         ↓ 需要时才加载
第 3 级：资源文件加载（按需）
  ├── 脚本文件
  ├── 模板文件
  └── 参考文档

code-reviewer/
├── SKILL.md          # 核心文件：元数据 + 指令
├── checklist.md      # 附属资源：审查清单
└── report-template.md # 附属资源：报告模板

---
name: code-reviewer
description: Review code for best practices, security issues, and performance. Use when reviewing PRs or analyzing code quality.
---
 
# Code Review Instructions
 
## Process
1. Scan all changed files
2. Check for security vulnerabilities (SQL injection, XSS, auth bypass)
3. Evaluate performance implications
4. Verify error handling completeness
5. Check test coverage
 
## Output Format
Provide a structured report with:
- 🔴 Critical issues (must fix)
- 🟡 Warnings (should fix)
- 🟢 Suggestions (nice to have)
- ✅ What's done well

请创建一个 Skill，用于 [任务描述]：
1. 在 [.claude/skills/ 或 .kiro/skills/] 下创建文件夹 [skill-name]/
2. 编写 SKILL.md，包含：
   - name 和 description 元数据
   - 详细的执行步骤
   - 输出格式要求
3. 添加必要的辅助文件（模板、脚本等）

主 Agent（编排者）
    │
    ├── 分析任务 → 拆分为子任务
    │
    ├── 生成 Subagent 1（调试专家）
    │   ├── 独立上下文窗口
    │   ├── 使用 Read + Bash + Grep 工具
    │   ├── 加载 "debugger" Skill
    │   └── 返回：根因分析 + 修复方案
    │
    ├── 生成 Subagent 2（安全审查）
    │   ├── 独立上下文窗口
    │   ├── 使用 Read + Grep 工具（只读）
    │   ├── 加载 "security-review" Skill
    │   └── 返回：安全漏洞报告
    │
    └── 综合所有 Subagent 结果 → 输出最终方案

---
name: debugger
description: Use immediately when errors occur. Find root cause, implement minimal fix, and verify.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---
 
You are a debugging specialist.
 
## Process
1. Capture exact error and reproduction steps
2. Locate the failing code area
3. Implement minimal, safe fix
4. Verify with tests

用户："审查这个 PR 的代码质量和安全性"
    │
    ▼
主 Agent 分析任务，决定使用 Subagent 并行处理
    │
    ├── Subagent 1：代码质量审查          [第 4 层：Subagents]
    │   ├── 加载 "code-reviewer" Skill    [第 3 层：Skills]
    │   ├── 通过 GitHub MCP 获取 PR diff  [第 2 层：MCP]
    │   └── 用 Read + Grep 分析代码       [第 1 层：Tools]
    │
    ├── Subagent 2：安全审查
    │   ├── 加载 "security-review" Skill  [第 3 层：Skills]
    │   ├── 通过 GitHub MCP 获取文件      [第 2 层：MCP]
    │   └── 用 Grep 搜索危险模式          [第 1 层：Tools]
    │
    └── 主 Agent 综合两个 Subagent 的报告
        └── 通过 GitHub MCP 发布 Review 评论

你需要 AI Agent 做什么？
    │
    ├── 执行单个原子操作（读文件、运行命令）
    │   └── → 使用 Tools（第 1 层）
    │
    ├── 访问外部系统数据（GitHub、数据库、Slack）
    │   └── → 使用 MCP（第 2 层）
    │
    ├── 重复执行某个标准化工作流
    │   └── → 创建 Skill（第 3 层）
    │
    └── 复杂任务需要并行处理或隔离上下文
        └── → 使用 Subagent（第 4 层）

我的项目需要优化上下文窗口使用。请帮我：
1. 将 CLAUDE.md 中的 [重复工作流描述] 提取为独立 Skill
2. 将常用的外部系统访问配置为 MCP Server
3. 为 [复杂任务] 设计 Subagent 编排方案
目标：主上下文只保留核心项目信息，专业能力按需加载。

cd my-saas-project
claude
 
# Claude Code 自动拥有 Read/Edit/Bash/Grep/Glob 等工具
> 分析项目结构，列出所有 API 路由

# 连接 GitHub，让 Claude Code 能直接操作 PR 和 Issue
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
 
# 连接 PostgreSQL，让 Claude Code 能直接查询数据库
claude mcp add --transport stdio postgres \
  --env DATABASE_URL=postgresql://localhost:5432/mydb \
  -- npx -y @bytebase/dbhub
 
# 连接 Sentry，让 Claude Code 能查看生产错误
claude mcp add --transport http sentry https://mcp.sentry.dev/sse

mkdir -p .claude/skills/pr-reviewer

---
name: pr-reviewer
description: Review pull requests for our Next.js + Prisma project. Use when reviewing PRs or before merging code.
---
 
# PR Review Instructions
 
## Tech Stack Context
- Next.js 14 App Router
- TypeScript strict mode
- Prisma ORM + PostgreSQL
- Tailwind CSS
 
## Review Checklist
1. **类型安全**：检查是否有 `any` 类型、缺少类型注解
2. **API 路由**：验证输入校验、错误处理、认证检查
3. **数据库**：检查 N+1 查询、缺少索引、事务使用
4. **安全**：SQL 注入、XSS、认证绕过、密钥泄露
5. **性能**：不必要的重渲染、大数据量处理、缓存策略
6. **测试**：新功能是否有对应测试
 
## Output Format
按严重程度分类输出：
- 🔴 **必须修复**：安全漏洞、数据丢失风险
- 🟡 **建议修复**：性能问题、代码规范
- 🟢 **可选优化**：代码风格、可读性

mkdir -p .claude/agents

---
name: debugger
description: Debugging specialist for production errors. Use when Sentry reports errors or tests fail.
tools: Read, Bash, Grep, Glob
model: sonnet
---
 
You are a debugging specialist for our Next.js + Prisma project.
 
## Process
1. Read the error message and stack trace
2. Use Grep to find related code
3. Identify root cause
4. Propose minimal fix with explanation
5. Suggest a test to prevent regression
 
## Rules
- Never modify production database
- Always explain WHY the bug occurred
- Prefer minimal changes over refactoring