ctkrug/skillcheck

# Skillcheck **▶ 在线演示：[apps.charliekrug.com/skillcheck](https://apps.charliekrug.com/skillcheck/)** [](https://github.com/ctkrug/skillcheck/actions/workflows/ci.yml) [](LICENSE) [](package.json) **在损坏的 agent 指令静默失败之前将其捕获。** Skillcheck 是一个用于校验引导编程 agent 的文件的 linter：`CLAUDE.md`、 `AGENTS.md` 以及 skill frontmatter (`SKILL.md`)。这些文件没有编译器，也没有 schema，因此拼错的 `name:`、为空的必填字段，或者两个 skill 声明了 相同的 slug，都不会抛出错误。它们只会悄悄地失效，而 agent 会 忽略你写的一半内容。Skillcheck 就是这些格式此前一直缺失的反馈循环。 ``` $ npx skillcheck .claude/skills .claude/skills/deep-research/SKILL.md error 4:1 missing-field skill frontmatter is missing required key `name` warn 6:14 description-too-long description is 1180 chars (limit 1024) .claude/skills/pdf/SKILL.md error 2:9 duplicate-name skill name `research` also declared in deep-research/SKILL.md 2 errors, 1 warning across 2 files ``` ## 适用人群 适用于任何在共享代码库中维护 `.claude/skills` 目录或 `AGENTS.md` 的人， 在这种情况下，一个损坏的 skill 会静默失效，直到任务出了 差错才有人注意到。将 Skillcheck 接入 CI，出错的指令文件会直接导致构建 失败，而不是让你的 agent 去承受错误。 ## 存在意义 `CLAUDE.md` / `AGENTS.md` / skill frontmatter 格式正在发展之中，且规范比较 宽松。目前没有官方的校验器，因此真实的失败模式（那些因为“agent 没有读取到我的 skill”而浪费你一整个调试过程的错误） 会一直隐身，直到真正反噬你。正确地识别出这些失败模式，而不仅仅是检查 “这是否是有效的 YAML”，才是其核心目的所在。 ## 可检测的问题 - **缺失 frontmatter 字段。** 缺少 `name` 或 `description` 的 skill，或者 未闭合的 `---` 块，永远无法加载。Skillcheck 会将其标记为错误。 - **Skill 名称冲突。** 声明了相同 `name` 的两个 skill 会互相 覆盖；只有一个会胜出，而且具体是哪一个是不确定的。 - **重复或拼错的键。** 重复的 `name:`（YAML 会静默保留其中一个），或者 像 `nmae:` 这样的拼写错误，会导致真正需要的字段缺失。 - **为空的必填字段。** `name: ~` 虽然显示为存在，但解析为空， 这正是本工具要捕获的典型静默失败。 - **薄弱的触发器。** 如果 `description` 中没有“use when...”（在……时使用）之类的引导，它就不会被可靠地 触发；Skillcheck 会对此发出警告。 - **命名规则。** `name` 必须是 kebab-case 格式，并且（对于 skill 而言）要与其所在的 目录名相匹配，否则 runtime 无法解析它。 - **长度限制。** 过长的描述会被模型宿主 截断，该检查会针对多行（`|` / `>`）描述进行计算。 - **无效的 skill 引用。** 正文中提到的 `/skill-name` 无法解析到当前 集合中的任何 skill。 每一项检查都可以通过 `skillcheck.json` [进行配置](docs/RULES.md#configuring-rules)：你可以禁用某条规则，或更改其严重级别。请查阅完整的 [规则参考](docs/RULES.md)、[`docs/VISION.md`](docs/VISION.md) 了解问题背景，以及 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 查看 代码库结构图。 ## 两套前端，一个引擎 - **CLI。** `npx skillcheck ` 可在 CI 或 pre-commit hook 中对代码库进行 lint。 - **Web 校验器。** 将文件粘贴到 [托管页面](https://apps.charliekrug.com/skillcheck/) 即可立即获得带有逐行注释的报告。规则相同，且无需安装。 这两者调用的都是 [`src/`](src/) 中完全相同的纯 JavaScript 引擎，因此 CLI 和 网站在校验结果上绝不会有分歧。 ## 快速开始 ``` git clone https://github.com/ctkrug/skillcheck cd skillcheck node bin/skillcheck.js examples # lint the bundled examples node bin/skillcheck.js --init my-skill # scaffold a lint-clean starter skill npm test # run the test suite ``` 无需安装任何依赖：该引擎是仅依赖标准库的 Node ESM。 常用 flags：`--json`（机器可读输出）、`--max-warnings `（遇到警告也判定为 CI 失败）、`--config ` / `--no-config`、`--init [name]`。 ## 在 CI 中使用 为每一次合并设置关卡，确保 skill 集合有效。将此步骤添加到 GitHub Actions workflow 中，一旦 skill 损坏，它就会使该作业失败： ``` - name: Lint agent instruction files run: npx skillcheck .claude/skills ``` 遇到警告（例如薄弱的触发器）也判定为失败，而不仅是遇到错误时： ``` - run: npx skillcheck --max-warnings 0 .claude/skills ``` ### Pre-commit hook 在问题提交前将其拦截。将以下内容保存为 `.git/hooks/pre-commit`（并 对其执行 `chmod +x`），或者将该命令接入你选用的 pre-commit 框架： ``` #!/bin/sh # 阻止破坏任何 agent instruction file 的 commit。 npx skillcheck .claude/skills || { echo "skillcheck found problems: fix them or commit with --no-verify" >&2 exit 1 } ``` 将其指向存放你的 `SKILL.md` / `CLAUDE.md` / `AGENTS.md` 文件的任意目录。在旁边放置一个 [`skillcheck.json`](docs/RULES.md#configuring-rules) 即可调整哪些规则作为通过标准。 ## 技术栈 - **引擎：** 纯 ES-module JavaScript，零 runtime 依赖，因此它可以 在 Node 和浏览器中原样运行。 - **CLI：** Node 18+，使用 `node:test` 进行测试。 - **Web 校验器：** 静态、独立的页面，使用相对资源路径，无需 服务器，可部署到任何子路径下。 ## License MIT © Charlie Krug。请参阅 [`LICENSE`](LICENSE)。 Charlie 的更多项目 → [apps.charliekrug.com](https://apps.charliekrug.com)

标签：AI辅助编程, LNA, MITM代理, SOC Prime, 开发工具, 自定义脚本, 验证工具