用途
该工具用于在提交技能 PR 之前,对 skills/ 目录下的技能执行与 CI 相同的宿主兼容性门禁检查。检查目标是 Codex 与 Cursor 的副本是否可安全安装,而非 Claude 运行时质量。
适用时机
- 在
skills/下新增或编辑技能时。 - 将技能复制到
.agents/skills/或.cursor/skills/时。 - 评审询问某技能是否可安全安装到 Codex 或 Cursor 时。
- CI 报告
validate-skill-host-compat.js的发现时。
主要能力
脚本作为跨目录的门禁,补充了 validate-skills.js(仅检查 SKILL.md 是否存在、name/description 是否为可用 YAML)和 tests/ci/codex-skill-surface.test.js(仅覆盖 .agents/skills/)的不足:
- 在可执行的 bash、sh、zsh 代码块中出现仅 Claude 支持的替换变量时判定失败,包括
$CLAUDE_SESSION_ID、$CLAUDE_SKILL_DIR、$CLAUDE_PLUGIN_ROOT、$CLAUDE_PROJECT_DIR、$ARGUMENTS。Codex 会将这些符号当作普通文本保留;在 Codex 副本中应将$CLAUDE_PROJECT_DIR改写为$(pwd)或显式路径。 - Codex 副本只允许使用
name、description、metadata、license、allowed-tools字段;origin: ECC可保留在规范的skills/副本中,但必须在 Codex 副本中移除。 - 在
agents/openai.yaml中列出且具有skills/目录的技能,必须存在.agents/skills/<name>/。Cursor 副本是可选的;存在时name:必须与目录名一致。 - CONTRIBUTING 检查清单项(When to Activate、Anti-Patterns、name 与目录一致、500/800 行上限)默认仅警告,使用
--strict-checklist时才失败。 validate-skills.js的 frontmatter WARN 默认行为保持不变。
使用方式
从仓库根目录运行:
node scripts/ci/validate-skill-host-compat.js
仅打印统计而不判定失败:
node scripts/ci/validate-skill-host-compat.js --inventory
将检查清单警告升级为失败:
node scripts/ci/validate-skill-host-compat.js --strict-checklist
斜杠命令:
$skill-host-compat
$skill-host-compat --inventory
反模式
- Codex 与 Cursor 的投影必须在可执行代码块中解析仅 Claude 的替换变量;规范 Claude 作用域的示例仍有效。
- POSIX
$1、${1}参数含义不明确,需人工审查,不应让该门禁直接失败。 - 禁止使用未解析的投影示例,例如:
echo "$CLAUDE_SESSION_ID"
ls "$CLAUDE_SKILL_DIR"
node "$CLAUDE_PLUGIN_ROOT/scripts/setup.js" $ARGUMENTS
cd "$CLAUDE_PROJECT_DIR"
- 不要在
.agents/skills/的 Codex 副本中添加version:或origin:。 - 不要将
validate-skills.js通过视为 Codex 安全。 - 不要要求每个
skills/条目都必须有 Cursor 副本。
最佳实践
- 若 CONTRIBUTING 模板要求,规范副本保留
origin: ECC。 - 在 Codex 副本中移除
origin、version和argument-hint。 - 在 bash 代码块中展示可跨宿主的命令(npx、ecc 或已解析的根路径)。在 Codex 副本中将
$CLAUDE_PROJECT_DIR改写为$(pwd)或显式路径。规范说明中可保留有效的 Claude 作用域形式;在目标投影中解析宿主变量。 - 新增技能时,在运行
npm test之前先运行此脚本。 - 使用
--inventory查看检查清单警告数量而不使失败。
相关技能
skill-comply:运行时行为追踪,非宿主可移植性。skill-stocktake:对已安装的~/.claude/skills做整体审计。skill-scout:创建新技能前搜索已有技能。
限制
资料仅描述该脚本的检查范围与用法,未提供图形界面、收费模式、支持平台或效果指标等信息。