skill-doctor

Skill Doctor

使用 ai-skillet 针对受支持的扩展技能方言提供的权威验证器，审计本地目录和已安装的 技能根目录，并且仅在收到请求时进行范围有限的元数据修复。

参数

• --root PATH：扫描此目录或已安装的技能根目录。可重复指定。默认值：当前工作目录。
• --skill NAME：将诊断和修复限制在名称匹配的技能目录中。可重复指定。
• --format text|json：选择报告格式。默认值：text。
• --fix-safe：创建缺失的 agents/openai.yaml 文件，或更新不匹配的 policy.allow_implicit_invocation。
• --dependencies-only：仅报告格式错误或无法解析的 skill-dependencies 声明。不可与 --fix-safe 同时使用。

工作流

1. 要求 PATH 中存在 ai-skillet 1.0.0 或更高版本，然后运行：

   ai-skillet doctor
   

   将每个解析出的调用选项及其值作为单独的参数追加，并保留引号中的值。例如， --root '/path with spaces' --format json 会添加两个选项；使用不带参数的形式即可采用默认值。

2. 当其他命令或 Agent 将使用结果时，使用 JSON：

   ai-skillet doctor --root . --format json
   

3. 阅读发现的问题后，再运行安全修复：

   ai-skillet doctor --root . --fix-safe
   

4. 手动编辑后，重新运行时不要使用 --fix-safe。

如需对目录执行仅检查依赖项的门禁，请运行：

ai-skillet doctor --root . --dependencies-only

发现的问题

• 将 error 级别的问题视为目录缺陷，应阻止发布或同步。
• 将 warning 级别的问题视为需要审核的目录卫生问题。
• JSON 输出使用架构版本 1，包含结构化的根目录、计数、发现的问题和安全修复记录。每条发现都包含其代码、严重级别、路径、已知时的行号、是否可修复，以及消息。
• 前言验证接受可移植的 Agent Skills 字段、Claude Code 扩展和仓库扩展组成的受支持并集。它会报告未知顶层字段、无效的字段、条目和元数据值类型、无效的枚举值，以及未搭配 context: fork 使用的 agent 或 background。
• 显式设置 disable-model-invocation: false 和 user-invocable: true 只是重申生效的默认值，会被接受且不会产生问题。
• 提示词卫生警告仅供参考，且绝不会自动修复：过时的模型固定版本、体积过大的无条件 Markdown 参考资料、相互冲突的要求/禁止措辞，以及缺少完成证据。
• 协调豁免错误仅作报告：coordination: exempt 必须与目录中的规范 coordination-exempt 句子同时出现在普通 Markdown 正文中。行内代码、围栏代码或缩进代码、引用块，以及标题为 Example 或 Examples 的章节均不算作声明。--fix-safe 不会修复任一部分。
• 依赖项错误会拒绝非数组、空、非字符串、重复、格式错误、顺序不正确、自引用或无法解析的本地声明。外部 ORG/REPO#SKILL 标识符仅进行格式检查，不访问网络。
• 在 --dependencies-only 模式之外，仍可执行元数据、OpenAI 策略、协调、资源、README、提示词卫生和 CLI 版本检查。
• 使用 JSON 输出中的 path 和 line 精确定位后续编辑位置。

安全修复策略

--fix-safe 仅可执行以下操作：

• 创建缺失的 agents/openai.yaml，并根据 SKILL.md 确定 policy.allow_implicit_invocation 的值。
• 当现有 allow_implicit_invocation 布尔值与 disable-model-invocation 不一致时，更新该值。

每项获准的修复都会先暂存，再通过原子重命名写入，并在更新时保留目标文件的权限。安全修复失败时会以 3 退出，且不会部分重写目标文件。

--fix-safe 不会重写前言、描述、README 行、references/version.txt 或相对链接。未知字段、无效类型或值、跨字段错误以及协调声明仅作报告。请手动进行这些编辑，并通过全新审计验证。

相关技能

• skill-doctor 只审计你传入的根目录；不会搜索根目录。要查找机器上的技能安装位置、重复项和交叉引用，请使用 ai-skillet map。

退出代码

• 0：检查结果干净，或所有请求的安全修复均已成功，且没有剩余问题。
• 1：审计已完成，但仍有问题；应将其报告为待审核事项，而不是操作崩溃。
• 2：参数无效或环境无法读取。
• 3：请求的安全修复失败。

面向用户的输出

确保 --format json 输出有效且不带任何修饰。对于面向用户的输出，开头应使用 ### 🩺 Skill Doctor — ✅ clean、### 🩺 Skill Doctor — ⚠️ review required 或 ### 🩺 Skill Doctor — ⛔ blocked（退出代码为 2/3 时），然后用精简表格展示根目录及错误/警告/修复数量。将安全修复与剩余问题分开列出。对于需要审核或受阻的结果，以最简手动后续操作收尾；对于干净的结果，在摘要后结束。路径、行号、代码、原始问题、命令和诊断信息必须保持原样。