技能创作最佳实践

1. 命名

好的命名

• code-review — 清晰，动词+名词
• data-export — 简洁，用途明确
• wechat-publisher — 平台+动作

避免的命名

• CodeReview — 大写
• code_review — 下划线
• cr — 过短，含义不清
• my-awesome-super-cool-tool — 过长

2. 描述

描述应在一句话内说清"做什么"和"适用场景"。

好的描述

自动审查代码变更，识别潜在 bug、安全漏洞和代码风格问题，支持多种编程语言。

需要改进的描述

代码工具。（太短） 这是一个非常强大的工具，可以帮助你完成很多工作，包括但不限于代码审查、格式化、重构等众多功能。（太长，没重点）

3. 正文结构

使用步骤化结构

## 核心逻辑

### 步骤 1: 数据采集
从指定 API 获取原始数据...

### 步骤 2: 数据清洗
去除空值、标准化格式...

### 步骤 3: 结果输出
生成报告并保存...

避免大段文字墙

用列表、表格、代码块拆分内容：

## 配置项

| 参数 | 默认值 | 说明 |
|------|--------|------|
| timeout | 30 | 超时秒数 |
| retry | 3 | 重试次数 |

4. 示例

提供至少 2 个真实示例，覆盖典型使用场景：

## 示例

### 示例 1: 基本用法

**输入:**
\```
review PR #123
\```

**输出:**
\```
发现 3 个问题:
1. [安全] SQL 注入风险 (line 42)
2. [风格] 命名不规范 (line 87)
3. [建议] 可简化逻辑 (line 120)
\```

5. 注意事项

明确说明限制和前提条件：

## 注意事项

- 需要 Python 3.8+
- API 调用有频率限制（每分钟 60 次）
- 不支持二进制文件处理

6. 版本管理

遵循 语义化版本：

• 1.0.0 → 1.1.0：新增功能，向后兼容
• 1.0.0 → 2.0.0：破坏性变更
• 1.0.0 → 1.0.1：Bug 修复

7. 目录组织

skills/
└── my-skill/
    └── my-skill/
        ├── SKILL.md          ← 核心
        ├── assets/           ← 图片等资源
        │   └── diagram.png
        └── references/       ← 参考文档
            └── api-spec.md

8. 验证

提交前务必运行验证：

python tools/skill_validator.py validate skills/my-skill

确保：

• ✅ 无错误
• 尽量减少警告（非标准字段可接受）