kurtpayne/skillscan-lint

# skillscan-lint [](https://github.com/kurtpayne/skillscan-lint/actions/workflows/ci.yml) [](https://github.com/kurtpayne/skillscan-lint/actions/workflows/codeql.yml) [](https://pypi.org/project/skillscan-lint/) [](https://hub.docker.com/r/kurtpayne/skillscan-lint) [](LICENSE) [](pyproject.toml) **用于 AI agent 技能文件的质量检查工具。** 在它们进入生产环境之前，捕捉模棱两可的含糊词汇、不明确的指令、缺失的元数据，以及技能图问题（循环、悬空引用、损坏的文件链接）。 兼容来自 [skills.sh](https://skills.sh)、[ClawHub](https://clawhub.ai) 的技能，以及任何基于 `SKILL.md` 的技能包。 ## 安装说明 ``` pip install skillscan-lint ``` 或者无需安装直接运行： ``` docker run --rm -v "$PWD:/work" kurtpayne/skillscan-lint scan /work/skills/ ``` ## 快速开始 ``` # Lint 单个 skill 文件 skillscan-lint scan SKILL.md # Lint 整个 skills 目录（包括 graph 检查） skillscan-lint scan ./skills/ --graph # 以 JSON 格式输出以便进行 CI 集成 skillscan-lint scan ./skills/ --format json # 列出所有规则 skillscan-lint rules ``` ### 示例输出 ``` SKILL.md QL-004 WARNING Weasel intensifier "basically" weakens the instruction. QL-009 ERROR Description too short (8 words). Minimum is 10. QL-015 WARNING TODO marker found — remove before publishing. GR-002 ERROR Skill "data-fetcher" references "parser" which does not exist. GR-006 WARNING Broken file reference: "references/auth.md" does not exist. 2 errors, 3 warnings ``` ## 规则 skillscan-lint 自带两个规则族： ### 质量规则 (`QL-*`) | 规则 | 严重程度 | 捕捉内容 | |------|----------|-----------------| | QL-001 | WARNING | 指令中的被动语态 | | QL-004 | WARNING | 模糊强调词 (`basically`, `very`, `essentially`) | | QL-008 | WARNING | 模糊动词 (`handle`, `manage`, `deal with`) | | QL-009 | ERROR | 描述过短 (< 10 个词) | | QL-010 | WARNING | 描述过长 (> 150 个词) | | QL-011 | ERROR | 缺少 `description` 字段 | | QL-012 | ERROR | 缺少 `name` 字段 | | QL-013 | WARNING | 名称未采用 `snake_case` 格式 | | QL-014 | WARNING | 缺少 `version` 字段 | | QL-015 | WARNING | 正文中存在 TODO/FIXME 标记 | | QL-016 | WARNING | 最高级词汇 (`best`, `perfect`, `ultimate`) | | QL-017 | WARNING | 名词化 (`optimization` → `optimize`) | | QL-018 | WARNING | 冗余短语 (`end result`, `past history`) | | QL-019 | WARNING | 流行语 (`leverage`, `synergy`, `paradigm`) | | QL-020 | WARNING | 模棱两可的词汇 (`might`, `could possibly`) | | QL-021 | ERROR | 句子过长 (> 35 个词) | | QL-022 | WARNING | 指令正文过长 (> 500 行) | | QL-023 | WARNING | 缺少 `## Usage` 或 `## Overview` 部分 | | QL-024 | WARNING | 缺少 `## Examples` 部分 | 运行 `skillscan-lint rules` 获取带有描述的完整列表。 ### 图规则 (`GR-*`，需要 `--graph`) 图规则会分析跨技能目录的 **调用图** —— 哪些技能调用了哪些技能、它们引用了哪些文件，以及依赖结构是否合理。 | 规则 | 严重程度 | 捕捉内容 | |------|----------|-----------------| | GR-001 | ERROR | 技能调用图中存在循环 (A → B → A) | | GR-002 | ERROR | 悬空引用（技能调用了不存在的技能） | | GR-003 | WARNING | 孤立的入口点（调用了其他技能但从未被调用 —— 如果是故意的，请添加 `entry_point: true`） | | GR-004 | WARNING | 中心技能（入度过高 —— 单点故障） | | GR-005 | WARNING | 未记录的依赖项（被引用的技能没有 `## Usage` 或 `## Overview` 部分） | | GR-006 | WARNING | 技能内部损坏的文件引用（Markdown 链接指向不存在的 `.md` 文件） | 图的边从三个来源进行解析，按可靠性排序： 1. **Front-matter 键** —— `invoke:`、`calls:`、`depends_on:`、`uses:`、`requires:`，包含技能名称或文件路径 2. **指向 `SKILL.md` 文件的 Markdown 链接** —— `[skill name](../other-skill/SKILL.md)` 3. **路径解析** —— 包含 `/` 或以 `.md` 结尾的 front-matter 值将相对于技能文件进行解析 技能包内的参考文档、README 文件和其他支持性的 `.md` 文件**不会**被视为图节点 —— 它们会由 GR-006 检查是否存在损坏的链接。 ## CI 集成 ### GitHub Actions ``` - name: Lint skills run: | pip install skillscan-lint skillscan-lint scan ./skills/ --graph --format json > report.json ``` ### Pre-commit hook ``` # .pre-commit-config.yaml repos: - repo: https://github.com/kurtpayne/skillscan-lint rev: v0.3.0 hooks: - id: skillscan-lint args: [--graph] ``` ### CI 中的 Docker ``` - name: Lint skills run: | docker run --rm -v "${{ github.workspace }}:/work" \ kurtpayne/skillscan-lint scan /work/skills/ --graph --format json \ > skillscan-lint-report.json ``` ## 技能图示例 给定一个技能目录： ``` skills/ data-fetcher/SKILL.md (invoke: parser) parser/SKILL.md (invoke: data-fetcher) ← cycle! formatter/SKILL.md (invoke: missing-skill) ← dangling ref ``` 运行 `skillscan-lint scan ./skills/ --graph` 将报告： ``` GR-001 ERROR Cycle detected: data-fetcher → parser → data-fetcher GR-002 ERROR Skill "formatter" references "missing-skill" which does not exist. ``` ## 相关项目 - **[skillscan-security](https://github.com/kurtpayne/skillscan-security)** — AI 技能的安全扫描器：prompt 注入、IOC 匹配、恶意软件检测、基于 ML 的分类器 - **[skills.sh](https://skills.sh)** — AI agent 技能的社区注册表 - **[ClawHub](https://clawhub.ai)** — MCP 技能市场 ## 许可证 Apache-2.0。详见 [LICENSE](LICENSE)。

标签：AI代理, CI/CD, Python, SOC Prime, 云安全监控, 代码检查, 开发工具, 无后门, 静态分析