SkillDoctor 快速入门

这是什么？适合谁？

SkillDoctor 是 Agent Skills 的质量门禁：lint 官方规范、审计危险指令、检查同一个 SKILL.md 在 Claude Code、Cursor、Codex、OpenCode、Gemini CLI、GitHub Copilot 上能否真正移植。一句话总结：Vercel 的 npx skills 负责安装 skill，SkillDoctor 负责判断该不该留。

适合人群：维护 skills 仓库的作者、批量引入第三方 skill 的团队、想给 skill 发布流程加 CI 门禁的工程团队。 使用前提：Node.js 18.18+、npx 可用。

快速上手（3 步）

第一步：直接 npx 运行

npx --yes github:xyiqq/skilldoctor --help

无需安装，一条命令看全部能力。

第二步：三连检查

npx --yes github:xyiqq/skilldoctor lint ./my-skill    # 规范校验
npx --yes github:xyiqq/skilldoctor audit ./my-skill   # 危险指令审计
npx --yes github:xyiqq/skilldoctor compat ./my-skill  # 六平台兼容性

第三步：接入 CI

npx --yes github:xyiqq/skilldoctor ci ./my-skill

一条命令整合三查，非零退出码直接挡住合并——skill 的发布门禁就此建立。

初级用法

• lint：校验 SKILL.md 对 Agent Skills 官方规范的符合度（结构、frontmatter、必填字段），中英双语文档开箱即用。
• audit：扫描危险指令（越权操作、不安全命令、提示注入面），第三方 skill 引入前必跑。
• compat：六大平台（Claude Code / Cursor / Codex / OpenCode / Gemini CLI / GitHub Copilot）逐一检查兼容性，提前发现”在 A 好用在 B 失灵”。

高级玩法

1. 供应链把关流水线：引入任何第三方 skill 的标准流程——npx skills 安装 → SkillDoctor audit → compat → 通过才进团队仓库。
2. 自有 skill 仓库 CI：给每个 skill 目录配 skilldoctor ci 的 GitHub Actions，规范漂移与危险指令在 PR 阶段拦截。
3. 跨平台发布矩阵：发布前用 compat 输出生成”支持平台矩阵”写进 README，用户预期管理一步到位。

常见踩坑（5 条）

踩坑 1：Node 版本过低

• 现象：npx 运行报语法错误
• 原因：要求 Node.js 18.18+
• 解决：升级 Node 后重试

踩坑 2：audit 误当杀毒软件

• 现象：期待百分百拦截恶意 skill
• 原因：audit 是静态审计危险指令模式，不是完整沙箱分析
• 解决：audit 结果 + 人工复核 + 运行环境隔离三管齐下

踩坑 3：compat 结果与实际不符

• 现象：标记兼容但运行出错
• 原因：各平台 skill 加载机制演进快，规则库有滞后
• 解决：compat 当初筛，关键平台实际跑一遍冒烟任务

踩坑 4：对单个 SKILL.md 之外的目录跑 lint

• 现象：报找不到 skill 结构
• 原因：检查目标应是 skill 目录（含 SKILL.md）
• 解决：确认路径指向 skill 根目录

踩坑 5：忽略中英双输出差异

• 现象：看漏关键警告
• 原因：输出为双语，长警告易被略读
• 解决：CI 里只认退出码，人工审查时慢读 audit 段

FAQ（5 个常见问题）

Q1：SkillDoctor 免费吗？ A：MIT 开源免费，npx 直接跑。

Q2：它和 skill 的关系是什么？ A：它不提供功能 skill，而是给 skill 生态做质检——“skill 生态治理元工具”。

Q3：六个平台的兼容规则会更新吗？ A：规则库随各平台演进维护，以仓库更新为准（本站采集时 2026-08-16 仍在活跃更新）。

Q4：能检查自定义 agent 框架的 skill 吗？ A：compat 聚焦六大主流平台；自研框架的规则需自行扩展。

Q5：CI 模式和三个单命令什么区别？ A：ci 是三查合一并按 CI 语义返回退出码，适合流水线；单命令适合交互排查。

小技巧（5 条）

1. 先 audit 后 lint：安全优先于规范，第三方 skill 尤其如此。
2. 矩阵存档：每次 compat 输出存档，平台规则变化时可 diff 对比。
3. 团队黑名单联动：audit 发现的危险模式沉淀进团队审查清单。
4. —help 先看：子命令参数有更新，以 —help 输出为准。
5. 锁定版本用：CI 里固定 commit hash 调用（github:xyiqq/skilldoctor#），避免上游突变。

进阶学习建议

• 阅读 agentskills.io 规范，理解 lint 背后的官方标准
• 研究 audit 的危险指令模式库，学习 skill 供应链安全的威胁模型
• 对比六平台 skill 加载机制的差异（compat 规则的来源），为自己的 skill 选择最大公约数写法
• 把 SkillDoctor 接入你的 skill 发布流程，建立”未过门禁不上线”的团队惯例

参考链接

• SkillDoctor GitHub 仓库
• Agent Skills 规范

本文基于公开资料于 2026-08-17 整理，社区指标反映 GitHub 公开数据。独立实测未进行，功能和配置项可能随版本更新而变化，请以官方文档为准。