技能介绍

解决什么问题

当你维护一个 SKILL.md 文件或整组技能文件时，常会遇到三类隐藏问题：语法层面的错误（如格式不匹配、标记误用）、语义层面的矛盾（如指令模糊、示例失效），以及兼容性层面的缺失（如未适配特定 Agent 平台的规则）。这些问题可能导致技能加载失败、执行逻辑混乱，甚至被目标平台直接拒绝。手动排查这类问题效率极低——尤其当技能目录包含多个文件或跨平台适配时，很难快速定位所有潜在风险点。

核心能力与工作逻辑

技能检查器通过 skillcheck CLI 提供了结构化验证流程。默认运行的符号检查会扫描文件结构、标记格式和指令完整性，生成包含错误、警告和信息三类诊断的报告。退出码的设计直接对应验证结果：0 代表无错误，1 代表存在错误或 --strict 模式下的警告，2 代表输入或参数错误，3 则表示符号检查通过但语义自评发现了错误。

语义验证环节支持两种工作流：一是通过 LLM 进行自我批判，生成提示词并接收返回的 JSON 结果，用于识别指令中的模糊表述或逻辑矛盾；二是针对能力图谱类工作，通过特定参数支持更复杂的技能关系验证。配置文件 skillcheck.toml 可预设 CLI 默认参数和 frontmatter 扩展字段，让团队能统一验证规则，减少重复操作。

适用边界与注意点

该工具的验证逻辑严格基于 SKILL.md 的规范格式，仅适用于符合该规范的技能文件或目录。目前支持的平台包括 Claude Code、Codex、Hermes Agent 等，但未覆盖所有 Agent 环境，跨平台使用时需额外验证目标平台的兼容性。语义自评功能依赖 LLM 的输出质量，极端情况下可能出现误判，建议结合人工复核处理关键技能。配置文件中的扩展字段会影响验证规则，修改后需通过完整测试确认不会影响现有技能的验证结果。