skill-lint

# Skill 格式审查工具 对指定的 skill 进行格式合规性审查，生成结构化的审计报告。 ## 审查流程 ### 1. 扫描目标技能 使用 Glob 工具列出技能目录下的所有文件： ``` <skill-path>/ ├── **/*.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. **[问题标题]** - 位置: `文件路径` - 建议: 优化建议 ### 信息提示 - [提示信息] ## 建议操作 ### 删除文件 | 文件路径 | 原因 | |----------|------| | `path/to/file.md` | 与 SKILL.md 重复 | | `path/to/old.md` | 引用不存在的脚本 | ### 更新文件 | 文件路径 | 修改内容 | |----------|----------| | `SKILL.md` | 更新 description 格式 | | `config.example.yaml` | 移除未使用的字段 | ### 新增文件 | 文件路径 | 用途 | |----------|------| | `assets/config.example.yaml` | 配置模板 | ## 审查完成 - 总问题数: N - 严重问题: N - 建议优化: N - 信息提示: N ``` ## 使用方法 用户提供要审查的技能路径，AI 执行以下步骤： 1. 使用 Glob 列出技能目录所有文件 2. 使用 Read 读取 SKILL.md 和其他关键文件 3. 按检查清单逐项检查 4. 生成结构化审查报告 ## 规范参考 详细检查清单见 [references/skill-standards.md](references/skill-standards.md) 规范依据：项目根目录的 `SKILL-DEV-GUIDE.md`