Skill 格式审查工具

对指定的 skill 进行格式合规性审查，生成结构化的审计报告。

审查流程

1. 扫描目标技能

使用 Glob 工具列出技能目录下的所有文件：

/
├── /*.md
├── /*.py
├── /*.yaml
├── /*.json
└── ...

2. 检查目录结构

验证是否符合标准目录结构：

skill-name/
├── SKILL.md # 必需
├── LICENSE.txt # 可选
├── references/ # 可选
├── scripts/ # 可选
└── assets/ # 可选

检查项：

• - [ ] SKILL.md 是否存在
• [ ] 是否有不规范的目录（如 test/、docs/ 应改为 references/）
• [ ] 是否有不应提交的文件（如 pycache/、.env）

3. 检查 Frontmatter

解析 SKILL.md 的 YAML frontmatter：

yaml

---

name: skill-name
description: 功能描述。本技能应在...时使用
license: MIT License - 详见 LICENSE.txt

---

检查项：

• - [ ] name 字段是否存在且格式正确
• [ ] description 字段是否存在
• [ ] description 是否使用第三人称（本技能应在...时使用）
• [ ] description 是否包含触发场景描述
• [ ] description 是否包含负向触发条件（不要用于...）
• [ ] description 长度是否 ≤ 1024 字符
• [ ] 是否有 license 字段
• [ ] 是否有多余的 version 字段（应删除）

4. 检查 SKILL.md 行数

检查项：

• - [ ] SKILL.md 行数是否 ≤ 500 行（超出应拆分到 references/）

5. 检查目录层级

检查项：

• - [ ] references/ 是否为扁平结构（只允许一级子目录）
• [ ] scripts/ 是否为扁平结构（只允许一级子目录）
• [ ] assets/ 是否为扁平结构（只允许一级子目录）

6. 检查文档一致性

扫描所有 .md 文件，提取引用的文件路径：

提取模式：

• - scripts/xxx.py
• assets/xxx.yaml
• references/xxx.md
• 相对路径引用

检查项：

• - [ ] 引用的脚本文件是否存在
• [ ] 引用的配置文件是否存在
• [ ] 引用的参考文档是否存在
• [ ] README.md 是否与 SKILL.md 内容重复

7. 检查冗余内容

检查项：

• - [ ] 是否有根目录 README.md（应删除，与 SKILL.md 重复）
• [ ] references/ 中的文档是否都引用了实际存在的文件
• [ ] 是否有过时的文档（描述已废弃的功能）
• [ ] SKILL.md 中是否有大段代码（>20行应移至 scripts/）

8. 检查配置文件

检查项：

• - [ ] 配置模板是否使用 .example. 命名
• [ ] 实际配置文件是否被 .gitignore 忽略
• [ ] config.example.yaml 的字段是否与实际代码匹配

9. 检查技能协作规范

检查项：

• - [ ] 是否直接引用其他技能的内部脚本路径（应改为自然语言描述）
• [ ] 协作描述是否使用松耦合方式

10. 检查模块化设计

检查项：

• - [ ] 独立功能是否解耦到单独脚本
• [ ] 是否存在跨 skill 直接调用内部脚本（应通过 AI 协调）

11. 检查安全审计

检查项：

• - [ ] 无硬编码 API keys
• [ ] 无危险删除命令（rm -rf ~、rm -rf /、rm -rf $HOME）
• [ ] 删除命令是否使用安全方式（trash 或 find -delete）

12. 检查输出模式

检查项：

• - [ ] 是否提供输出格式模板（对于需要一致性输出的技能）
• [ ] 模板严格度是否适中（严格需求用 ALWAYS，灵活需求用 use your best judgment）
• [ ] 是否提供输入/输出示例（对于质量关键的输出）
• [ ] 示例是否覆盖典型场景（至少 2-3 个）

13. 检查工作流模式

检查项：

• - [ ] 复杂任务是否有流程概览（步骤编号清晰）
• [ ] 是否有条件分支逻辑（使用粗体问题 + 箭头指向）
• [ ] 每个分支是否有完整的执行步骤

14. 检查 CHANGELOG 规范

检查项：

• - [ ] 是否存在 CHANGELOG.md 文件（推荐有）
• [ ] 格式是否符合规范（版本号 + 日期 + 变更内容）
• [ ] 版本号是否遵循语义化版本（v1.0.0 格式）
• [ ] 日期格式是否统一（YYYY-MM-DD）
• [ ] 变更类型是否清晰（新增/修改/修复/移除）

CHANGELOG 格式规范：
markdown

Changelog

All notable changes to this skill will be documented in this file.

[v1.1.0] - 2026-02-24

新增

• - 添加了 XXX 功能

修改

• - 优化了 YYY 逻辑

修复

• - 修复了 ZZZ 问题

[v1.0.0] - 2026-02-01

新增

• - 初始版本发布

15. 检查版本号管理

检查项：

• - [ ] SKILL.md frontmatter 中是否有多余的 version 字段（应删除）
• [ ] 版本信息是否统一在 CHANGELOG.md 中管理
• [ ] 如有版本号，是否与 CHANGELOG.md 最新版本一致

注意：版本号不应出现在 SKILL.md 的 frontmatter 中，所有版本变更应在 CHANGELOG.md 中记录。

16. 检查可编排性设计

对于可能参与复杂工作流编排的技能，检查以下项：

检查项：

• - [ ] 是否有明确的输入/输出声明（在 SKILL.md 中）
• [ ] 是否遵循单一职责原则（每个 Skill 只做一件事）
• [ ] 是否具有幂等性（多次执行结果相同）
• [ ] 复杂编排是否有 references/workflow.md

输入/输出声明格式：
markdown

输入/输出

输入

• - 必需：--input 参数说明
• 可选：--flag 参数说明

输出

• - 输出文件：output/path.md 说明
• 副作用：如创建目录、修改文件等

单一职责检查：

• - 技能是否只完成一个核心任务
• 是否有多个不相关的功能混在一起

幂等性检查：

• - 多次运行是否产生相同结果
• 是否有累积效应（如追加写入而非覆盖）

生成审查报告

报告格式

markdown

[skill-name] 格式审查报告

审查时间: YYYY-MM-DD HH:MM
技能路径: /path/to/skill

审查摘要

检查项	状态	问题数
目录结构	✅/⚠️/❌	N
Frontmatter

✅/⚠️/❌ | N | | SKILL.md 行数 | ✅/⚠️ | N | | 目录层级 | ✅/⚠️ | N | | 文档一致性 | ✅/⚠️/❌ | N | | 冗余内容 | ✅/⚠️/❌ | N | | 配置文件 | ✅/⚠️/❌ | N | | 技能协作 | ✅/⚠️/❌ | N | | 模块化设计 | ✅/⚠️/❌ | N | | 安全审计 | ✅/⚠️/❌ | N | | 输出模式 | ✅/⚠️/❌ | N | | 工作流模式 | ✅/⚠️/❌ | N | | CHANGELOG | ✅/⚠️/❌ | N | | 版本号管理 | ✅/⚠️/❌ | N | | 可编排性 | ✅/⚠️/❌ | N |

详细问题

严重问题（必须修复）

1. 1. [问题标题]

- 位置: 文件路径:行号 - 规范: 违反的规范条款 - 建议: 具体修复建议

建议优化

1. 1. [问题标题]

- 位置