moonrunnerkc/skillcheck

针对 `SKILL.md` 文件的静态分析器。根据 [agentskills.io 规范](https://agentskills.io/specification)校验 frontmatter、正文大小、文件引用以及跨 agent 兼容性。无网络调用。无 LLM API 调用。无文件修改。 786 个测试覆盖了所有规则模块。 ## 安装 ``` pip install skillcheck ``` 需要 Python 3.10 或更高版本。如需更准确的 token 估算，请安装可选的额外依赖： ``` pip install "skillcheck[tiktoken]" ``` ## 用法 ``` skillcheck SKILL.md # validate one file skillcheck skills/ # scan a directory for files named SKILL.md skillcheck SKILL.md --format json skillcheck --help # full flag reference ``` 输出示例： ``` ✔ PASS skills/claude-api/SKILL.md line 2 ⚠ warning frontmatter.name.reserved-word Name contains the term 'claude'. line 4 · info frontmatter.field.ecosystem Field 'license' is ecosystem-common. Checked 18 files: 18 passed, 0 failed, 29 warnings ``` ## GitHub Action ``` - uses: moonrunnerkc/skillcheck@v1 with: path: skills/ ``` 诊断结果将以内联 PR 注释的形式显示。相关输入说明请见 [`action.yml`](action.yml)。 ## pre-commit ``` repos: - repo: https://github.com/moonrunnerkc/skillcheck rev: v1.3.0 hooks: - id: skillcheck ``` 该 hook 默认传递 `--no-color` 参数，以确保捕获的 pre-commit 日志保持整洁。你可以通过 `.pre-commit-config.yaml` 中的 `args:` 进行覆盖或扩展（例如：`args: ["--no-color", "--strict"]`）。 ## 检查内容 - **Frontmatter**：必填字段、类型、名称与描述的长度限制、保留字冲突。 - **描述质量**：针对动作动词、触发短语、关键词、具体程度和长度进行 0-100 分的评分。 - **大小**：根据 agentskills.io 的披露预算检查行数与 token 阈值。 - **引用**：失效链接、跳出 skill 目录的路径转义、深度限制。 - **跨 agent 兼容性**：Claude Code, VS Code, Codex, Cursor。 - **能力图**（`--analyze-graph`）：孤立的能力、未使用的输入、未产生的输出、未被引用的工具。 - **历史记录账本**（`--history`）：每次运行跟踪校验结果的、按 skill 划分的只追加（append-only） JSON 文件。 ## Agent 模式 当调用的 agent 可以执行 prompt 时，skillcheck 能够接收其响应，并将分析结果合并到报告中： ``` skillcheck SKILL.md --emit-critique-prompt > prompt.txt # 将 prompt.txt 交给 agent，然后： skillcheck SKILL.md --ingest-critique response.json ``` 能力图提取（`--emit-graph-prompt` / `--ingest-graph`）也存在相同的流程。Prompt 变体可以通过 `--critique-agent` 和 `--graph-agent`（`claude`、`codex`、`cursor`）针对不同 agent 进行调整。 ## 退出码 | 代码 | 含义 | |---|---| | `0` | 无错误。除非设置了 `--strict`，否则仅有警告时也会以 0 退出。 | | `1` | 出现一个或多个错误。此外：带有 `--strict` 时的警告（总括性的 `--strict-vscode` / `--strict-cursor` 仅会提升其自身诊断的级别；该总括性参数还会提升任何仅有警告的运行的级别）。此外：带有 `--fail-on-regression` 时的 `history.skill.regressed`。此外：任何接收数据的解析失败。 | | `2` | 输入或参数错误（缺少路径、标志冲突、输入格式错误）。 | | `3` | 符号化检查通过，但接收到的审查报告了语义错误。 | 当 `1` 和 `3` 同时适用时，以 `1` 为准，以便 CI 消费者能看到更高严重级别的信号。 ## 配置 默认配置位于从校验路径向上查找发现的 `skillcheck.toml` 文件中。可以通过 `--config PATH` 为每次调用进行覆盖。特定于组织的 frontmatter 键应放在 `[frontmatter] extension_fields` 下。可以使用 `[frontmatter] reserved_words = ["acme", "internal"]` 覆盖名称保留字列表（空数组将恢复为默认值）。 `--ignore PREFIX` 会抑制任何规则 ID 以 `PREFIX` 开头的诊断信息。该前缀会与完整的点分规则 ID 进行匹配，因此以下三个层级均有效：顶级类别（`--ignore sizing`）、类别加字段组合（`--ignore frontmatter.name`），或完全限定的规则（`--ignore compat.unverified`）。该标志可重复使用。 ## 文档 - [`CONTRIBUTING.md`](CONTRIBUTING.md)：测试、维护者工作流、规则编写约定。 - [`docs/case-study-v1-real-world-runs.md`](docs/case-study-v1-real-world-runs.md)：针对 Anthropic skills 语料库的运行测试。 - [`docs/case-study-silent-skill-failure.md`](docs/case-study-silent-skill-failure.md)：VS Code dirname 不匹配事件。 - [`skills/skillcheck/SKILL.md`](skills/skillcheck/SKILL.md)：一个能通过所有规则的 SKILL.md。 ## 发布 带有标签的发布（`v*`）携带由 `actions/attest-build-provenance@v1` 签发的 SLSA 构建来源证明。要在安装前验证发布构件： ``` gh attestation verify dist/skillcheck-*.whl --owner moonrunnerkc ``` 这可以确认 wheel 包是由 `moonrunnerkc/skillcheck` CI 从打标签提交的源代码构建的。未打标签的构建（PR 和 main 分支 CI）不提供证明。 ## 许可证 MIT。详见 [`LICENSE`](LICENSE)。

标签：AI智能体, Python, Python安全, SOC Prime, 云安全监控, 代码质量检查, 开发工具, 无后门, 逆向工具, 静态分析