---

name: skill-authoring description: Skill 编写与评价规范。当涉及创建 skill、编写 SKILL.md、优化 skill、评价 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. 运行测试 → 验证功能正确

输入输出说明

明确 Skill 期望的输入和产出：

要素	说明	示例
输入	用户需要提供什么	代码片段、需求描述、配置文件
输出	Skill 会产出什么	优化后的代码、设计文档、执行结果

## 输入
- 用户提供的 [X]（如：待优化代码）

## 输出
- 生成的 [Y]（如：重构后的代码 + 说明）

边界条件

说明 Skill 不适用的场景，避免误用：

## 不适用场景
- 当 X 情况时，请使用其他方法
- 不支持 Y 类型的任务
- 超出范围：Z

成功标准

提供可验证的完成标准：

## 成功标准
- [ ] 输出包含 A
- [ ] 格式符合 B
- [ ] 通过 C 验证

检查清单

基础要求（必须满足）：

• name：小写+连字符
• description：包含"做什么"和"什么时候用"
• 有实际内容（非空）

规范要求（应当满足）：

• 用表格代替长段落
• 条件用数字而非模糊描述
• 文件 < 500 行
• 有代码示例

优秀要求（争取满足）：

• 语言无关（方法论优先）
• 结构清晰（概览→表格→流程→示例）

卓越要求（加分项）：

• 有输入输出说明
• 有边界条件/不适用场景
• 有成功标准

评分标准

分数	等级	说明
90-100	卓越	完全符合规范，有输入输出、边界条件、成功标准
70-89	优秀	符合规范，结构清晰，有示例，语言无关
50-69	合格	基本可用，有 description 和内容，但有明显不足
30-49	较差	缺少关键要素（如无示例、结构混乱）
0-29	很差	基本不可用（无内容、无法理解）