agent-skill-linter

Agent 技能检查器

检查 Agent 技能是否符合规范并已准备好发布。

预期布局

支持两种布局，根据目标位置是否存在 .claude-plugin/plugin.json 自动检测：

• 单个技能 — 检查目标为 skill/ 子目录（旧版仓库则为仓库根目录）。如果目标指向采用 skill/ 布局的仓库根目录，也可以正常工作：检查器会将目标重定向到 skill/，并在 stderr 中说明。
• 插件 — 检查目标为插件根目录；会检查清单文件和每个 skills/<name>/ 目录。

请参阅 references/layouts.md，了解布局图示、逐文件约定和各模式的检测规则。

分诊工作流

目标： 要检查的技能目录——当前目录（.）或用户提供的路径。

第 1 步 — 全面了解情况

./scripts/skill-lint.py check <target>

查看输出中的错误和警告；在继续第 2 步之前，确认已全面了解情况。

第 2 步 — 优先修复错误

规则 1 错误（SKILL.md 规范合规性）会阻止发布。先修复这些错误。该规则对 Claude Code 扩展字段的检查结果属于警告，在第 4 步处理。

只有在重新运行第 1 步后未报告任何错误，才能继续第 3 步。如果经过两次修复仍有错误，立即停止并向用户展示检查器输出。

第 3 步 — 自动修复警告

./scripts/skill-lint.py check <target> --fix

对于没有 CLI 的可修复规则，请使用 references/fix-templates.md 中的模板。

继续第 4 步之前，确认已无可自动修复的警告。

第 4 步 — 手动处理剩余警告

CSO 描述前缀（规则 11）、Python 调用方式（规则 13）、SKILL.md 中 README 级别的章节（规则 19）、frontmatter 中的 Claude Code 扩展字段（规则 1 警告：如果技能仅适用于 Claude Code，则保留这些字段；如果要发布跨平台版本，则删除这些字段）——请参阅下方的规则表。

继续第 5 步之前，确认所有剩余警告均已解决（或明确接受）。

第 5 步 — 语义审查：CSO 信号

规则 11 会检查结构模式，但不检查含义。阅读 frontmatter 中的 description 和 name，并确认：它们是否纯粹用于路由？

示例请参阅 references/semantic-rules.md — 规则 12 和 18。

如果描述符合以下情况，请标记：

• 列举该技能检查、处理或支持的内容
• 读起来像功能摘要或工作流概览
• 包含说明性标签（Triggers on:、Use cases:、Checks:）或多个句子
• 可以缩减为一个短语，且不损失路由精度

如果名称读起来像名词短语而非动作，请标记——优先使用动名词形式（creating-skills、processing-pdfs），而不是名词形式（skill-creator、pdf-processor）。简短且广为人知的名称（pdf、commit）可以保留。

好的描述只说明触发条件。其他所有内容都应放在技能正文中。

继续第 6 步之前，确认描述和名称纯粹用于路由。

第 6 步 — 语义审查：入门提示词

规则 7 会检测提示词是否存在，但不会判断它们是否实用。阅读 Usage 部分中的入门提示词，并确认：它们是否对应真实且彼此不同的触发场景？

如果符合以下情况，请标记：

• 含糊或笼统（例如，Use this skill、Run the linter）
• 描述的都是同一场景，只是措辞略有不同
• 未涵盖真实用户可能遇到的各种情境

继续第 7 步之前，确认入门提示词涵盖的用例确实各不相同。

第 7 步 — 语义审查：内容重叠

检查器不会检查这一点。请确认：SKILL.md 和 README 是否用不同措辞传达了相同信息？

示例请参阅 references/semantic-rules.md — 规则 8。

标记改述后的重复内容。SKILL.md 应面向 Agent（分诊工作流、规则）；README 应面向人类读者（安装、使用示例）。

继续第 8 步之前，确认已无改述后的重复内容。

步骤 8 — 语义审查：渐进式披露

规则 15 会标记已知的参考资料类关键词，但并非所有需要按需查阅的内容都有可识别的标题。请问：Agent 会按需查阅本节，还是会一开始就读完？

示例请参阅 references/semantic-rules.md — 规则 16。

如果某些章节符合以下情况，请标记并移至 references/：

• 无论标题名称如何，它们都属于参考资料（例如“背景”“工作原理”）
• 内容密集或有条件限制——即使篇幅很短、未被规则 15 捕获也一样
• 包含特定步骤的详细内容块，会让主工作流变得冗长，但无需在一开始阅读

还要问：如果某个章节有条件限制（“之后……”“一旦……”“如果……”），它的标题或首行是否指明了 Agent 能观察到的具体触发事件？

示例请参阅 references/semantic-rules.md — 规则 27。

如果条件章节的触发条件含糊不清，请标记。例如“查看输出后”“了解上下文后”这类表述会让 Agent 不知道何时进入该章节。

在继续步骤 9 之前，请确认所有需要按需查阅的内容都已移至 references/，且所有条件章节都指明了可观察的触发条件。

步骤 9 — 语义审查：多步骤工作流质量

仅当技能包含多步骤工作流（3 个或更多 ### Step N 标题）时，才执行此步骤。

阅读每个步骤的正文并思考：每个实质性步骤是否都说明了 Agent 如何判断该步骤已完成？

示例请参阅 references/semantic-rules.md — 规则 22。

如果某个步骤的正文只描述了要做什么，却没有退出条件、关卡提示或“仅在……时继续”的信号，请标记该步骤。极短的步骤（单行）无需明确的关卡提示。

还要问：工作流中是否至少有一个步骤会检查实际的工具输出，而不只是口头声明？

示例请参阅 references/semantic-rules.md — 规则 23。

如果每个步骤都规定了要执行的操作，却没有任何步骤要求 Agent 查看工具实际返回的内容，请标记该工作流。

还要问：如果工作流会根据工具输出循环执行，是否指明了重试上限和备用方案？

示例请参阅 references/semantic-rules.md — 规则 26。

如果工作流要求 Agent 重试、迭代或等待工具成功，却没有“直到成功”为止之外的退出条件，请标记该工作流。

在继续步骤 10 之前，请确认以上三个问题都已得到满足。

步骤 10 — 语义审查：朴素直白的文风

规则 28 会检查面向读者的文档（README、用户指南）中容易识别的问题。请站在读者的角度逐一阅读——读者是一位了解 Agent 技能、但从未接触过本项目的开发者——并思考：它是否用简短、主动的句子说明了技能的用途和目标用户，同时没有营销辞藻或带有 AI 腔调的填充语？

检查清单和委派说明请参阅 references/semantic-rules.md — 规则 28。

如果可以使用 critiquing-articles，请委派它进行 AI 腔调审查（参考资料中包含体裁说明和备用检查清单）。

提出改写建议，并仅在用户同意后应用。继续步骤 11 之前，请确认所有面向读者的文档都采用了朴素直白的文风。

步骤 11 — 将 Info 项作为润色项处理

正文长度（规则 9）、非标准目录（规则 10）、技能隔离（规则 17）。

检查内容

#	规则	严重级别	自动修复
1	SKILL.md 规范合规性（通过 skills-ref）；Claude Code 扩展字段（disable-model-invocation、model、hooks……）仅发出警告	错误 / 警告	—
2	LICENSE 文件存在，采用 Apache-2.0 或 MIT 许可，并标注当前年份	警告	部分
3	SKILL.md frontmatter 中包含 metadata.author	警告	是
4	README 徽章（CI、许可证、Agent Skills）	警告	是
5	.github/workflows/ 中包含 CI 工作流	警告	是
6	README 包含安装部分	警告	是
7	README 包含使用部分，其中有入门提示词和 CLI 小节	警告	部分 + 步骤 6
9	SKILL.md 正文少于 500 行	信息	—
10	标记非标准目录	信息	—
11	CSO：描述以 "Use when..." 开头	警告	步骤 5
13	Python 调用方式一致性（uv 项目中使用 uv run python）	警告	—
14	渐进式披露：嵌入式模板（4 个反引号的代码围栏）→ references/	警告	是
15	渐进式披露：参考资料级别的标题（Troubleshooting、FAQ、Advanced……）→ references/	警告	是 + 步骤 8
17	技能隔离：SKILL.md 位于仓库根目录，且旁边有非技能文件（SKILL.md 位于 skill/ 后不再提示）	信息	—
19	分工：SKILL.md 中包含 README 级别的部分（安装、功能、入门指南……）	警告	—
20	分类工作流有 3 个以上步骤，但没有语义审查步骤（例如“询问：它是否……”）	信息	步骤 5–10
21	scripts/ 中的 Python 入口脚本缺少 PEP 723 内联依赖元数据	警告	—
24	插件清单 .claude-plugin/plugin.json 存在、可解析，并包含 name 和 version	错误	—
25	导入非标准库代码的技能脚本声明了依赖来源（PEP 723、插件根目录中的 pyproject.toml 或同级目录）	错误	—
28	面向用户的文档（README、用户指南）中的普通文本：营销式夸张表述、主题被埋没或开篇铺垫冗长、句子或段落过长、连续使用破折号	信息	步骤 10

仅在插件模式下（lint 目标中存在 .claude-plugin/plugin.json）才会触发规则 24 和 25。

CLI 参考

./scripts/skill-lint.py check .                            # Auto-detect: skill, skill/ subdir, or plugin
./scripts/skill-lint.py check ./my-skill --fix             # Single-skill, auto-fix
./scripts/skill-lint.py check ./my-plugin                  # Plugin: validates manifest +
                                                           # iterates skills/<name>/
./scripts/skill-lint.py check ./my-skill --format json     # JSON output for CI

存在错误时退出代码为 1，否则为 0。