01MVP Starter Kit

Skill 的完整结构

my-skill/
├── SKILL.md          # [必需] 核心定义
├── scripts/          # [可选] 可执行脚本
│   ├── process.py
│   └── upload.js
├── references/       # [可选] 详细参考文档
│   ├── guide.md
│   └── examples.md
└── assets/           # [可选] 静态资源
    ├── template.json
    └── config.yaml

SKILL.md 详解

Frontmatter（元数据）

---
name: code-reviewer               # 唯一标识符
description: |                    # 触发条件和功能描述
  审查代码是否符合团队规范。
  使用场景：用户请求 review 代码、提交 PR 前、或提到"代码审查"时。
version: 1.0.0                    # [可选] 版本号
author: Your Name                 # [可选] 作者
tags: [code, review, quality]     # [可选] 标签
---

关键字段说明：

name（必需）

小写字母和连字符
简短且描述性
全局唯一

示例：

✅ code-reviewer
✅ multi-platform-adapter
❌ Code Reviewer（有空格）
❌ cr（太简短）

description（必需）

这是最重要的字段，决定 AI 什么时候调用这个 Skill。 Frontmatter 会被加载到系统提示词中，AI 根据 description 来判断当前任务是否需要调用这个 Skill。

写好 description 的三条原则：

同时说明"做什么"和"什么时候用" — 缺一不可
包含用户实际会说的话（触发词） — 包括技术术语和口语表达
控制长度，不超过 1024 字符 — 过长会占用上下文窗口，2-4 句话即可

禁止事项：

不能包含 XML 尖括号 < >，会导致解析错误
name 中不能包含 "claude" 或 "anthropic"（保留词）
name 不能有空格或大写

示例对比：

❌ 不好的 description：

description: Review code

太简短，AI 不知道什么时候用
没有触发关键词

❌ 不好的 description：

description: 帮助处理项目。

太模糊，几乎任何任务都能匹配

✅ 好的 description：

description: |
  审查代码的安全性、性能和代码风格。
  使用场景：
  - 用户请求 review 代码
  - 提交 PR 前的检查
  - 提到"代码审查"、"code review"、"检查代码"时
  重点关注：SQL 注入、XSS、性能瓶颈、命名规范

✅ 好的 description（含负向说明，避免过度触发）：

description: |
  用于 CSV 文件的高级数据分析（统计建模、回归分析、聚类）。
  不适用于简单数据查询（请使用 data-viz Skill）。

主体内容

建议这样写：

# [Skill 名称]

## 概述
[一句话说明这个 Skill 的作用]

## 使用场景
[什么时候用这个 Skill]

## 执行步骤

### 1. [第一步名称]
[详细说明]
- [子步骤 1]
- [子步骤 2]

### 2. [第二步名称]
[详细说明]

### 3. [第三步名称]
[详细说明]

## 输出格式
[期望的输出格式]

## 示例

### 示例 1：[典型场景]
输入：
[示例输入]

输出：
[示例输出]

### 示例 2：[边缘情况]
输入：
[示例输入]

输出：
[示例输出]

## 注意事项
- [注意事项 1]
- [注意事项 2]

写的时候注意这几件事：

用清晰的标题层级
- ## 主要部分
- ### 子步骤
- #### 细节说明
多用列表，少写长段落
- 更容易解析
- AI 更容易理解
- 用户更容易阅读
提供具体的示例
- 不要只说"格式化输出"
- 给出具体的输出格式
把边缘情况说清楚
- 空数据怎么处理
- 错误输入怎么处理
- 异常情况怎么处理

scripts/ 目录

什么时候用脚本

适合用脚本的场景：

格式化（JSON、XML、代码）
文件操作（上传、下载、转换）
API 调用（第三方服务）
数据处理（计算、统计、转换）
确定性任务（结果固定）

不适合用脚本的场景：

需要创意的任务（写作、设计）
需要理解上下文的任务
需要推理的任务

脚本示例

Python 脚本：

# scripts/format_json.py
import json
import sys

def format_json(input_file):
    """格式化 JSON 文件"""
    try:
        with open(input_file, 'r') as f:
            data = json.load(f)
        
        # 格式化：2 空格缩进，键名排序
        formatted = json.dumps(
            data, 
            indent=2, 
            sort_keys=True,
            ensure_ascii=False
        )
        
        print(formatted)
        return 0
    except Exception as e:
        print(f"错误：{e}", file=sys.stderr)
        return 1

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("用法：python format_json.py <input_file>")
        sys.exit(1)
    
    sys.exit(format_json(sys.argv[1]))

在 SKILL.md 中调用：

## 格式化 JSON

运行脚本：
`python scripts/format_json.py input.json`

脚本会：
- 验证 JSON 格式
- 统一缩进为 2 空格
- 按键名排序
- 输出格式化结果

Node.js 脚本：

// scripts/upload_image.js
const fs = require('fs');
const axios = require('axios');

async function uploadImage(imagePath, apiKey) {
  try {
    const imageBuffer = fs.readFileSync(imagePath);
    const base64Image = imageBuffer.toString('base64');
    
    const response = await axios.post('https://api.example.com/upload', {
      image: base64Image
    }, {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });
    
    console.log(JSON.stringify(response.data));
    return 0;
  } catch (error) {
    console.error(`错误：${error.message}`);
    return 1;
  }
}

const [imagePath, apiKey] = process.argv.slice(2);
if (!imagePath || !apiKey) {
  console.error('用法：node upload_image.js <image_path> <api_key>');
  process.exit(1);
}

uploadImage(imagePath, apiKey).then(process.exit);

脚本最佳实践

清晰的错误处理
- 捕获所有可能的错误
- 输出有用的错误信息
- 返回正确的退出码
标准的输入输出
- 用命令行参数传递输入
- 用 stdout 输出结果
- 用 stderr 输出错误
文档化
- 在脚本开头说明用途
- 提供使用示例
- 说明依赖项

references/ 目录

渐进式披露原则

核心思想：

SKILL.md 只包含核心流程（< 500 行）
详细文档放在 references/
AI 只在需要时才读 references

示例结构：

references/
├── guide.md           # 详细指南
├── examples.md        # 更多示例
├── edge-cases.md      # 边缘情况处理
├── api-reference.md   # API 文档
└── troubleshooting.md # 故障排除

在 SKILL.md 中引用：

## 高级用法

基础用法见上文。更多高级场景请参考：
- [详细指南](references/guide.md)
- [更多示例](references/examples.md)
- [边缘情况处理](references/edge-cases.md)

什么放在 references/

适合放在 references/ 的内容：

详细的 API 文档
大量的示例
复杂的边缘情况
故障排除指南
历史背景和设计决策

不适合放在 references/ 的内容：

核心执行步骤（应该在 SKILL.md）
触发条件（应该在 description）
常用示例（应该在 SKILL.md）

assets/ 目录

静态资源

常见的 assets：

assets/
├── templates/         # 输出模板
│   ├── report.md
│   └── config.json
├── configs/           # 配置文件
│   ├── rules.yaml
│   └── settings.json
├── styles/            # 样式文件
│   └── output.css
└── data/              # 参考数据
    └── examples.json

模板示例

Markdown 模板：

<!-- assets/templates/report.md -->
# {{title}}

## 概述
{{summary}}

## 详细信息

### 问题
{{#issues}}
- **{{severity}}**: {{description}}
  - 位置：{{location}}
  - 建议：{{suggestion}}
{{/issues}}

### 统计
- 总问题数：{{total_issues}}
- 严重问题：{{critical_issues}}
- 警告：{{warnings}}

## 建议
{{recommendations}}

在 SKILL.md 中使用：

## 输出格式

使用模板 `assets/templates/report.md` 生成报告。

替换以下变量：
- `{{title}}`: 报告标题
- `{{summary}}`: 概述
- `{{issues}}`: 问题列表
- `{{recommendations}}`: 建议

完整示例

示例：代码审查 Skill

code-reviewer/
├── SKILL.md
├── scripts/
│   ├── check_security.py
│   └── analyze_performance.js
├── references/
│   ├── security-checklist.md
│   └── performance-guide.md
└── assets/
    └── templates/
        └── review-report.md

SKILL.md：

---
name: code-reviewer
description: |
  审查代码的安全性、性能和代码风格。
  使用场景：用户请求 review 代码、提交 PR 前、或提到"代码审查"时。
  重点关注：SQL 注入、XSS、性能瓶颈、命名规范。
version: 1.0.0
author: Team
tags: [code, review, security, performance]
---

# Code Review Skill

## 概述
自动审查代码质量，发现安全漏洞、性能问题和代码风格问题。

## 使用场景
- 提交 PR 前的自查
- Code Review 辅助
- 代码质量检查

## 执行步骤

### 1. 安全检查
运行安全扫描脚本：
`python scripts/check_security.py <file_path>`

重点检查：
- SQL 注入风险
- XSS 漏洞
- 硬编码的密钥
- 不安全的依赖

详细清单见 [安全检查清单](references/security-checklist.md)

### 2. 性能分析
运行性能分析脚本：
`node scripts/analyze_performance.js <file_path>`

重点检查：
- 不必要的循环
- 重复计算
- 内存泄漏
- 过度渲染（React）

详细指南见 [性能优化指南](references/performance-guide.md)

### 3. 代码风格
检查：
- 命名规范（驼峰、下划线）
- 注释完整性
- 函数长度（< 50 行）
- 文件长度（< 500 行）

### 4. 生成报告
使用模板 `assets/templates/review-report.md` 生成报告。

## 输出格式

```markdown
# Code Review Report

## 安全问题
- [严重] SQL 注入风险 (line 42)
- [警告] 硬编码 API Key (line 15)

## 性能问题
- [警告] 不必要的循环 (line 78)

## 代码风格
- [提示] 函数过长 (line 100-180)

## 总结
- 严重问题：1
- 警告：2
- 提示：1

## 建议
1. 修复 SQL 注入风险
2. 将 API Key 移到环境变量
3. 优化循环逻辑

示例

示例 1：发现安全问题

输入：

def get_user(user_id):
    query = f"SELECT * FROM users WHERE id = {user_id}"
    return db.execute(query)

输出：

[严重] SQL 注入风险 (line 2)
- 问题：直接拼接 SQL 语句
- 建议：使用参数化查询
- 修复：query = "SELECT * FROM users WHERE id = ?"

示例 2：发现性能问题

输入：

function processItems(items) {
  for (let i = 0; i < items.length; i++) {
    for (let j = 0; j < items.length; j++) {
      // O(n²) 操作
    }
  }
}

输出：

[警告] 性能问题 (line 2-6)
- 问题：嵌套循环导致 O(n²) 复杂度
- 建议：使用 Map 或 Set 优化查找
- 预期改进：O(n²) → O(n)

注意事项

自动检查不能替代人工 Review
关注上下文，避免误报
优先修复严重问题


## 下一步

- 想开始创建 Skill → 看 [创建 Skill](/docs/skills/advanced)
- 想看开发者 Skill → 看 [开发者 Skill 推荐](/docs/skills/developer)
- 想看知名 Skill 系列 → 看 [baoyu-skills](/docs/skills/series/baoyu-skills) 或 [Matt Pocock Skills](/docs/skills/series/mattpocock-skills)

Skill 拆解