skill-check

SkillCheck（免费版）

依据 Anthropic 指南和 agentskills 规范检查技能。本文件包含免费版的验证规则。

想进行更深入的分析？ 升级到 Pro，即可使用反杂乱检测、安全扫描、Token 优化、WCAG 合规检查、企业级检查和 Eval Kit（自动为技能生成测试提示词）。

前提条件

• 具备文件读取能力的任意 AI 助手（Claude Code、Cursor、Windsurf、Codex CLI）
• 适用于任何平台（Unix/macOS/Windows）
• 无需特殊工具（只读；不可见 Unicode 检查也会使用 Grep，且仍为只读）
• 无需环境变量或 API 密钥；检查完全离线运行

接口

• 输入：SKILL.md 文件的路径，以及同一技能文件夹中的任意 references/*.md 文件
• 输出：验证报告，列出每个问题及其检查 ID、严重程度（Critical / Warning / Suggestion）、行号和修复方法；优点另列
• 模式：可独立检查单个技能，也可检查技能目录；每个技能生成一份报告

工作流

对每个目标技能，按顺序运行四个阶段。数据逐步传递：步骤 1 的文件列表传给步骤 2，加载的内容传给步骤 3，检查结果传给步骤 4。

• 步骤 1：定位 — 使用 Glob 查找目标 SKILL.md 文件
• 步骤 2：读取 — 加载 SKILL.md 内容和任意 references/ 文件
• 步骤 3：验证 — 对加载的内容应用下方各项规则
• 步骤 4：报告 — 列出发现的问题及其严重程度、行号和修复方法

执行限制：最多迭代 1 次：每个技能只进行 1 次验证。每个已定位的技能报告一次后即停止；如果无法读取 SKILL.md，则中止并在报告中说明。检查为只读且具幂等性，可安全重复运行；对未更改的文件重复运行会生成相同的报告。

---

免费版验证规则

下方每项检查的有效和无效示例见 references/examples.md。规则列于此处；示例另存于一个文件中，以便快速浏览本文件。

按顺序执行这些检查。每个小节都定义了要匹配的模式和要标记的问题。

1. Frontmatter 结构

每个 SKILL.md 都必须以 --- 标记之间的 YAML frontmatter 开头。

必填字段

字段	必填	规则
name	是	仅限小写字母和连字符，长度为 1–64 个字符，不得使用保留词
description	是	遵循 WHAT + WHEN 模式，长度为 1–1024 个字符

Frontmatter 安全性

检查 1.9-xml-in-frontmatter（Critical）：Frontmatter 值不得包含 XML 尖括号（< 或 >）。Frontmatter 会出现在 Claude 的系统提示词中；尖括号可能导致提示词注入。

检测：扫描所有 frontmatter 字符串值（name、description、compatibility 等）中的 < 或 > 字符。

修复：从 frontmatter 中移除尖括号。使用纯文本描述。SKILL.md 正文中可以使用 Markdown 格式和 XML 标签。

可选字段（规范）

agentskills.io 规范中定义的字段：

字段	用途
license	许可证名称或对随附许可证文件的引用
allowed-tools	技能可使用的工具（以空格分隔或采用 YAML 列表）
compatibility	平台兼容性信息（最多 500 个字符）
metadata	其他键值对

Claude Code 扩展

Claude Code 可识别（参见 Claude Code skills 文档），但不属于 agentskills.io 规范。其他 Agent 可能会忽略这些字段，claude.ai 上传和 Skills API 则会拒绝这些字段（参见 1.19）。

字段	用途
when_to_use	额外的触发上下文，会附加到技能列表中的 description 后
argument-hint	对预期参数的自动补全提示
arguments	用于 $name 替换的命名位置参数（以空格分隔的字符串或 YAML 列表）
model	覆盖模型（完整 ID，如 claude-opus-4-6；别名：opus、sonnet、haiku，或 inherit）
effort	工作量级别：low、medium、high、xhigh 或 max
disallowed-tools	技能处于活动状态时移除的工具（以空格或逗号分隔的字符串，或 YAML 列表）
context	运行上下文（子 Agent 使用 "fork"）
agent	context: fork 时的 Agent 类型
background	对于 context: fork，设为 false 可等待分叉结果（默认值：true）
hooks	生命周期钩子（PreToolUse、PostToolUse、Stop）
paths	限制技能自动激活时机的 Glob 模式（以逗号分隔的字符串或 YAML 列表）
shell	内联命令使用的 Shell：bash（默认值）或 powershell
user-invocable	在斜杠菜单中显示（默认值：true）
disable-model-invocation	仅可手动调用的技能

社区扩展

不属于任何规范，Claude Code 也不会读取（会静默忽略这些字段）。社区工具和注册表会使用这些字段。不要根据 1.8 或 1.19 将其标记出来。

字段	用途
category	用于发现和筛选的技能领域
produces	此技能输出的制品类型（以逗号分隔）
consumes	此技能从其他技能读取的制品类型（以逗号分隔）
type	技能类型指示符
author	技能作者
date	创建/更新日期

字段识别与取值

检查 1.8-unexpected-field（建议）：顶层键未出现在上述三个表格（规范、Claude Code、社区）中的任何一个中。Claude Code 会忽略未知键且不报告错误，因此拼写错误会被静默忽略；claude.ai 上传和 Skills API 则会直接拒绝该文件。metadata 下的键不受限制，永远不会被标记。

检查 1.13-disallowed-camelcase（建议）：disallowedTools 是子 Agent 使用的拼写。在 SKILL.md 中，该字段应为 disallowed-tools；驼峰式键会被忽略。应报告此项，而不是 1.8。

检查 1.12-maxturns-not-skill-field（建议）：maxTurns 是子 Agent 字段，而非技能字段。Claude Code 会在 SKILL.md 中忽略它。应报告此项，而不是 1.8。

检查 1.19-non-portable-field（建议）：在一条发现中列出所有存在于规范之外的键，包括 Claude Code 表格和社区表格中的键。Claude Code 会加载或忽略这些键，但 claude.ai 上传和 Skills API 仅接受 name、description、license、compatibility、metadata 和 allowed-tools。

检查 1.11-effort-invalid（警告）：effort 的值不是 low、medium、high、xhigh 或 max 之一。

检查 1.18-bool-value（警告）：user-invocable、disable-model-invocation 或 background 的值不是 true、false、yes、no、on、off、1 或 0（不区分字母大小写）。

检查 1.14-listing-cap（警告）：description 与 when_to_use 的字符数总和超过 1,536。技能列表会在该长度处截断合并后的文本，因此末尾的触发条件会丢失。请将主要用例放在前面。

检查 1.15-shell-invalid（警告）：shell 的值不是 bash 或 powershell。

检查 1.16-background-no-fork（建议）：设置了 background，但未设置 context: fork。此字段仅适用于分叉技能。

检查 1.17-paths-invalid（警告）：paths 不是 Glob 字符串（允许以逗号分隔）或 Glob 字符串的 YAML 列表，例如映射、数字、布尔值或空值。

类别验证

注意：category 是社区扩展，不属于 agentskills.io 规范。缺少 category 字段时不要标记。仅在字段存在时验证格式。

格式：字符串或字符串数组，只能包含小写字母、数字和连字符。

模式：^[a-z][a-z0-9-]*[a-z0-9]$（与 skill 名称使用相同规则）

常见类别：development、productivity、data、automation、writing、design、security、devops、api、testing、documentation、legal、financial、marketing、ai-ml

工件传递验证

注意：produces 和 consumes 是用于技能间工件传递的社区扩展。缺少字段时不要标记。仅在字段存在时验证格式。

格式：以逗号分隔的工件类型名称列表。每种类型只能包含小写字母和连字符。

已知工件类型：content-brief、knowledge-note、reading-log-entry、sift-article

检查 1.10-artifact-types（警告）：如果 produces 或 consumes 包含上述已知列表之外的类型，则标记为警告（而非错误）。新类型有效；已知列表只是初始集合，并非注册表。

检查 1.11-consumes-without-tools（警告）：如果技能声明了 consumes:，但其 allowed-tools 不包含 Read 或 Glob，则标记为警告。使用工件需要读取文件。

名称验证

模式：^[a-z][a-z0-9-]*[a-z0-9]$

命名建议：避免使用无法描述技能功能的通用词：helper、utils、tools、misc、stuff、things、manager、handler。特定于产品的词语（claude、anthropic、mcp）可以使用，但可能会限制其在不同 Agent 之间的可移植性。

描述验证

必须包含：

1. 做什么：说明技能功能的动作动词
2. 何时使用：说明何时使用该技能的触发短语
3. 关键能力（建议）：所处理的具体任务或文件类型

建议结构：[功能] + [使用时机] + [关键能力]

动作动词：Create、Generate、Build、Convert、Extract、Analyze、Transform、Process、Validate、Format、Export、Import、Parse、Search、Find

使用时机触发短语：“Use when”、“Use for”、“Use this when”、“Invoke when”、“Activate when”、“Triggers on”、“Auto-activates”、“Run when”、“Applies to”、“Helps with”

allowed-tools 验证

以空格分隔的格式（allowed-tools: Read Glob）和 YAML 列表格式均有效。两种格式示例请参阅 references/examples.md。

目录结构验证

根据 agentskills 规范，技能可以包含可选子目录：

目录	用途	验证
references/	附加文档（REFERENCE.md 等）	文件应为 .md 格式
scripts/	可执行代码（Python、Bash、JS）	应具有执行权限
assets/	静态资源（模板、数据）	无需验证

根据 agentskills 规范，技能文件夹中允许包含其他任何文件，包括 README.md。不要标记这些文件。

支持的技能路径格式：

• 标准：~/.claude/skills/{skill-name}/SKILL.md
• 命名空间：~/.claude/skills/{namespace}/{skill-name}/SKILL.md

命名空间支持：命名空间允许按来源（个人、团队、项目）组织技能：

• ~/.claude/skills/internal/weekly-reports/SKILL.md
• ~/.claude/skills/shared/code-review/SKILL.md

目录名称必须与技能名称一致：父目录名称必须与 frontmatter 中的 name 字段完全一致。

---

2. 命名质量

名称应使用描述性复合词，而非单个词语。

长度指南：最少 3 个字符，最佳为 10–30 个字符，最多 64 个字符。

反模式格式检查

检查 2.8-antipattern-format（建议）：当技能文档介绍反模式时（章节标题与“反模式”“不要做什么”“避免”“常见错误”“不良做法”“陷阱”等相符），内容应采用结构化格式（表格或项目符号列表），而不是大段文字。

触发条件：

• 反模式章节中有一行较长的说明文字（100 个或更多字符），且包含 don't/avoid/never
• 反模式章节中有 3 行或更多说明文字，且包含 3 条或更多规避指令

不会触发的情况：

• 章节已使用表格（| col | col |）或项目符号列表（- item）
• 章节标题与反模式关键词不符

---

3. 语义检查

验证技能指令的逻辑一致性和清晰度。

矛盾检测

标记同时要求和禁止同一操作的冲突指令。

模糊用语

标记需要更具体的模糊表述。“多个项目”或“正确设置”等术语不够精确。应使用确切数量或具体标准。

例外（不会标记）：

• 代码块或引用块中的术语
• 行内代码片段（反引号）中的术语；反引号括起的字面内容是引用示例，而非模糊表述
• 示例／用法／模式章节中的内容
• Before/After 和正确／错误对比行
• 后接限定词的术语（例如，“某些特定文件”）

输出格式规范

提及输出的技能应通过具体示例说明格式。

检测方式：

• 技能提及“output/returns/produces”，但没有 ## Output 章节
• 有输出章节，但缺少代码块、JSON 或表格

智慧箴言检测

检查 4.6-wisdom-platitude（建议）：检测缺乏可操作内容的泛泛建议（“智慧箴言”）。技能应包含具体指令，而非励志性文字。

三个检测层面：

1. 开篇模式：以智慧箴言开头的行，例如 “Remember that”、“It's important to”、“Keep in mind that”、“Think about”、“Never forget that”、“Always keep in mind”、“Consider the importance of”
2. 陈词滥调结构：行内 “[名词] is essential/crucial/important to [名词]” 模式
3. 模糊祈使句："Ensure quality"、"maintain standards"、"strive for best practices"

例外（不会标记）：

• 代码块或引用块中的内容
• 示例／用法／模式章节中的内容
• Before/After 和正面／负面对比行

描述触发式写法

检查 4.8-description-trigger-style（建议）：描述字段应写成触发条件，而非能力摘要。Claude 会扫描描述，以判断“是否有适用于此请求的技能？”以触发条件为导向的描述会在请求匹配时启动；以摘要为导向的描述则容易被忽略。

检测方式：描述以摘要模式而非触发模式开头：

• 摘要式开头（标记）：“This skill”、“A tool that”、“Provides”、“Offers”、“Handles”、“Manages”、“Enables”
• 触发式开头（通过）：“Use when”、“Generate”、“Build”、“Convert”、“Extract”、“Validate”、“Run”、“Create”、“Find”、“Search”

不会触发的情况：

• 描述以摘要式开头，但后文也包含 WHEN 触发短语（“Handles X. Use when user says Y” 即可）
• 描述以动作动词开头

严重程度：建议

修复方法：改用动作动词开头，并加入 “Use when” 子句。描述是路由指令，而非文档说明。

铁轨式约束检测

检查 4.9-railroading（建议）：技能应向 Claude 提供信息和上下文，而不是规定确切的操作顺序。过多的指令性措辞会降低 Claude 根据用户实际情况灵活调整的能力。

检测：统计示例块、代码块和反模式部分之外的指令性短语：

• “you must always”“always do exactly”“never deviate”“follow these exact steps”“do not change this”“this is the only way”“you are required to”

触发条件：非示例内容中有 5 个或更多指令性短语。

不会触发的情况：

• 指令性措辞位于代码块、引用块或示例标签内
• 指令性措辞位于反模式／注意事项部分（用于说明不该做什么）
• 技能属于安全关键型技能（安全、合规），需要严格指令

严重程度：建议

路由内容位置不当

检查 4.4：正文包含应放在 description 字段中的触发条件。

检测：正文包含与 ## When to Use 或 ## When to Use This Skill 匹配的标题，或正文中包含诸如“Activate when user”“Trigger this skill when”“Use this skill when”之类的路由短语。

问题：只有在调用 Skill 工具后，技能正文才会加载。放在正文中的触发条件不会影响路由决策。路由时 Claude 会读取 description 字段；“Use when”模式、触发关键词和示例短语都应放在那里。

严重程度：警告

修复方法：将正文部分中独有的触发内容合并到 description 字段，然后删除冗余的正文部分。

空洞内容

检查 22.7-hollow-content（建议）：如果注意事项／故障排除部分只有泛泛的填充内容，没有具体知识，则属于空洞内容。它声称提供经验之谈，实际却只给出陈词滥调。

检测：在 ## Gotchas／## Troubleshooting／## Tips／## Caveats／## Pitfalls 部分中，如果有 3 行或更多内容与下方列表中的泛泛填充短语匹配，且没有任何一行包含具体知识信号（具体阈值／带单位的数字、“X because Y”这类后果说明、编号调试步骤，或文件／函数引用），则触发。

follow team standards
ensure proper handling
handle appropriately
consider relevant factors
use appropriate methods
maintain quality

例外（不标记）：代码块内的内容；包含至少一个具体阈值、后果说明或调试步骤的部分。

克制原则未列出安全例外

检查 28.2-restraint-without-carveout（警告）：如果技能要求克制／保持精简，却从未明确列出验证、安全或无障碍方面的例外，则标记。没有这类例外的克制原则可能会鼓励跳过不可妥协的要求，而不只是避免过度设计。底线是“可以偷懒，但不能失职”。

检测：存在克制／避免过度构建指令（YAGNI、“保持精简”“不要过度构建／过度设计”“以能解决问题的最简单方案为准”“克制添加内容的冲动”“优先使用标准库”），并且没有任何一行同时包含保留／不得删减提示（“never cut”“always keep”“still required”“non-negotiable”）和安全相关名词（验证、安全、无障碍／a11y）。仅仅顺带提及“安全”或“验证”，但没有保留提示，不算作例外说明。

不会触发的情况：不存在克制指令；或存在明确的例外条款。

严重程度：警告

---

4. 质量模式（优点）

识别技能中的正面模式。这些内容会作为“优点”而非问题报告。检查 8.1–8.9 用于检测：示例部分、错误处理、触发短语、输出格式、结构化指令、前置条件、负向触发条件和注意事项部分。每项检查的检测模式和完整示例见 references/examples.md。

---

5. 不可见 Unicode（Cat 30）

不可见字符会向人工审核者隐藏指令，但每个 AI Agent 都能读取这些指令。对 SKILL.md 和所有 references/*.md 文件运行以下三项 Grep 搜索。不要依赖阅读文件来发现这些字符——它们不会显示出来；只有模式搜索才能可靠地找到它们。

ASCII 走私

检查 30.1-ascii-smuggling（严重）：Unicode 标签字符可承载完整的隐藏 ASCII 消息。

检测：Grep 模式 [\x{E0000}-\x{E007F}]。

豁免：格式正确的旗帜表情符号是此区块唯一的合法用途：U+1F3F4 后跟 2–6 个标签字母/数字，再加上取消标签 U+E007F（苏格兰/威尔士旗帜）。如果匹配项紧跟在 U+1F3F4 后面且以 U+E007F 结尾，则它是表情符号——不要标记。此区块中的其他任何内容都是走私。

报告：解码载荷（U+E0020–U+E007E 中的每个字符都以其码点减去 0xE0000 得到 ASCII），并在发现项中引用解码后的文本，让作者准确看到隐藏了什么。

Trojan-Source 双向覆盖字符

检查 30.2-bidi-override（严重）：双向控制字符会使显示的文本与实际文本不同（CVE-2021-42574）——一个看起来像图像的文件名，实际可能是可执行文件。

检测：Grep 模式 [\x{061C}\x{200E}\x{200F}\x{202A}-\x{202E}\x{2066}-\x{2069}]。

不触发的情况：技能确实包含阿拉伯语、希伯来语等从右向左书写的语言，且标记出现在这些文本中。仅含英文的技能、代码块、文件名或命令中出现的双向标记，始终都应作为发现项报告。

零宽字符

检查 30.3-invisible-run / 30.4-invisible-char：零宽字符会隐形地拆分单词或编码隐藏数据。

检测：Grep 模式 [\x{034F}\x{180E}\x{200B}\x{200C}\x{2060}\x{FEFF}\x{2061}-\x{2064}\x{206A}-\x{206F}]。

严重程度：同一行上连续匹配 10 个或以上为严重问题（30.3，隐藏数据通道；40 个或以上则毫无疑问）。成组出现 3 个或以上为警告，单独出现一个则为建议（30.4）。

豁免：文件首字符处的 U+FEFF 是工具留下的字节顺序标记——无需报告。零宽连接符和变体选择符被刻意排除在模式之外：它们在表情符号序列中（家庭表情符号、❤️）具有结构性作用，标记它们会让作者学会忽略这一类别。