| name | skill-authoring |
| description | Skill 编写规范。当涉及创建 skill、编写 SKILL.md、优化 skill 结构、skill 格式时使用。 |
Skill 编写规范
核心原则：表格 > 文字，数字 > 描述，示例 > 说明
Frontmatter
---
name: skill-name # 必需，小写+连字符，≤64字符
description: 做什么。当涉及 X、Y、Z 时使用。 # 必需，≤1024字符
allowed-tools: Read, Glob # 可选，限制可用工具
model: sonnet # 可选，指定模型
---
| 字段 | 必需 | 说明 |
|---|---|---|
| name | ✅ | 小写+数字+连字符 |
| description | ✅ | 做什么 + 什么时候用 |
| allowed-tools | ❌ | 限制工具范围 |
| model | ❌ | opus/sonnet/haiku |
Description 写法
❌ 模糊：数据处理相关功能
✅ 清晰：数据采集方案。当涉及新闻采集、公告采集、akshare API、定时任务时使用。
公式：[能力描述]。当涉及 [关键词1]、[关键词2]、[关键词3] 时使用。
文件大小
| 行数 | 状态 |
|---|---|
| < 300 | ✅ 理想 |
| 300-500 | ⚠️ 考虑拆分 |
| > 500 | ❌ 必须拆分 |
内容结构
# Skill 名称
## 快速概览（1-2句）
## 核心表格
| 条件 | 动作 |
|------|------|
## 流程图（ASCII）
A → B → C
## 代码示例
## 命令速查
AI 最爱的格式
| 格式 | 效果 | 示例 |
|---|---|---|
| 表格 | ⭐⭐⭐ | 条件→动作映射 |
| 数字条件 | ⭐⭐⭐ | ≥80 而非 "较高" |
| ASCII 流程图 | ⭐⭐ | A → B → C |
| 代码示例 | ⭐⭐ | 实际可运行代码 |
| 长段落 | ❌ | AI 容易遗漏细节 |
多文件结构
my-skill/
├── SKILL.md # 核心概览（< 300行）
├── DETAILS.md # 详细说明（按需加载）
└── EXAMPLES.md # 更多示例
SKILL.md 中引用：
详细说明见 [DETAILS.md](DETAILS.md)
通用性设计
原则：Skill 应该是方法论，而非工具手册
抽象层次
| 层次 | 说明 | 示例 |
|---|---|---|
| ❌ 具体命令 | 特定语言/工具 | grep -rn "pattern" --include="*.py" |
| ⚠️ 工具名称 | 可替换的工具 | "使用 grep 搜索" |
| ✅ 操作概念 | 语言无关 | "搜索匹配模式的内容" |
| ✅ 方法论 | 思维方式 | "全局搜索 → 验证 → 确认" |
从具体到抽象
| 具体（❌ 避免） | 抽象（✅ 推荐） |
|---|---|
*.py, *.js |
"所有代码文件" |
app/, src/ |
"主代码目录" |
grep, find |
"搜索工具" |
pip, npm |
"包管理器" |
pytest, jest |
"测试框架" |
语言无关清单
- 无具体文件扩展名（
.py,.js） - 无具体目录结构（
src/,app/） - 无具体工具命令（
grep,eslint） - 用概念描述代替具体实现
- AI 可根据项目语言自适应
示例对比
❌ 语言特定：
### Python 项目检查
1. 运行 `black` 格式化代码
2. 运行 `mypy` 类型检查
3. 运行 `pytest` 执行测试
✅ 语言无关：
### 代码质量检查
1. 格式化 → 统一代码风格
2. 类型检查 → 发现类型错误
3. 运行测试 → 验证功能正确
检查清单
- name：小写+连字符
- description：包含"做什么"和"什么时候用"
- 用表格代替长段落
- 条件用数字而非模糊描述
- 文件 < 500 行
- 有代码示例
- 语言无关（新增）
- 方法论优先（新增）