skill-lint

name	skill-lint
homepage	https://github.com/cat-xierluo/legal-skills
author	杨卫薪律师（微信ywxlaw）
version	1.4.0
description	Skill 格式审查工具，基于 docs/SKILL-DEV-GUIDE.md 规范对技能进行合规性审计。本技能应在用户需要审查 skill 格式合规性、检查 Frontmatter 与版本同步、检查文档与代码一致性、识别冗余内容、生成技能审计报告时使用。不要用于：代码审查、功能测试、非 skill 项目。
license	MIT License - 详见 LICENSE.txt

Skill 格式审查工具

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

审查流程

1. 扫描目标技能

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

<skill-path>/
├── **/*.md
├── **/*.py
├── **/*.yaml
├── **/*.json
└── ...

2. 检查目录结构

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

skill-name/
├── SKILL.md          # 必需
├── LICENSE.txt       # 可选
├── CHANGELOG.md      # 可选（推荐）
├── TASKS.md          # 可选（开发上下文，保留）
├── DECISIONS.md      # 可选（开发上下文，保留）
├── references/       # 可选
├── scripts/          # 可选
├── templates/        # 可选
└── assets/           # 可选

检查项：

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

豁免文件（以下文件为开发过程上下文，不应标记为不合规，不应建议删除）：

• TASKS.md — 任务追踪
• DECISIONS.md — 决策记录
• CHANGELOG.md — 变更日志

3. 检查 Frontmatter

解析 SKILL.md 的 YAML frontmatter：

---
name: skill-name
description: 功能描述。本技能应在...时使用
version: "1.0.0"
license: MIT
author: 杨卫薪律师（微信ywxlaw）
homepage: https://github.com/cat-xierluo/legal-skills
---

检查项：

• name 字段是否存在且格式正确
• description 字段是否存在
• description 是否使用第三人称（"本技能应在...时使用"）
• description 是否包含触发场景描述
• description 是否包含负向触发条件（"不要用于..."）
• description 长度是否 ≤ 1024 字符
• 是否有 license 字段
• 如有 version 字段，是否与 CHANGELOG.md 最新版本一致
• 如有 README 或 marketplace 索引，版本是否同步

4. 检查 SKILL.md 行数

检查项：

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

5. 检查目录层级

检查项：

• references/ 是否完全扁平（文件直接放在目录下，无子目录）
• scripts/ 是否完全扁平（文件直接放在目录下，无子目录）
• assets/ 是否完全扁平（文件直接放在目录下，无子目录）
• templates/ 是否完全扁平（文件直接放在目录下，无子目录）

注意：所有二级目录（references/、scripts/、assets/、templates/）下禁止创建子目录，文件必须直接放在目录根。

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 格式规范：

# 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 是否保留完整版本历史
• README 和 marketplace 中的版本是否与 CHANGELOG.md 最新版本一致
• source 是否未被不必要地强制要求（已有 homepage 时可省略）

注意：version 是公开发布推荐字段，不再视为违规；但 CHANGELOG.md 仍是版本历史来源，所有公开索引中的版本必须同步。

16. 检查可编排性设计

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

检查项：

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

输入/输出声明格式：

## 输入/输出

### 输入
- 必需：`--input` 参数说明
- 可选：`--flag` 参数说明

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

单一职责检查：

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

幂等性检查：

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

17. 检查依赖声明与防护

对于包含脚本的技能（scripts/ 目录非空），检查以下项：

检查项：

• SKILL.md 是否声明了依赖（哪些功能需要额外安装）
• 脚本中的硬依赖是否有 try/except 包裹并给出安装提示
• 脚本中的可选依赖是否有 try/except 包裹并设置降级标志
• requirements.txt 是否存在且只包含硬依赖（可选依赖不应列出）
• SKILL.md 中依赖安装说明是否就近放置（在对应功能章节内，而非文档末尾）

判断标准：

• 无脚本的纯 prompt 技能：跳过此检查
• 有脚本但无外部依赖（仅用标准库）：在 SKILL.md 中注明"无需额外安装依赖"
• 有脚本且有外部依赖：必须通过上述所有检查项

生成审查报告

报告格式

# [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 |
| 依赖声明与防护 | ✅/⚠️/❌ | 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

规范依据：docs/SKILL-DEV-GUIDE.md