SuperAPI AI 工具集

skill-host-compat

编程与开发

查看项目

更新于 11-10 16:20

技能介绍

用途

该工具用于在提交技能 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:创建新技能前搜索已有技能。

限制

资料仅描述该脚本的检查范围与用法,未提供图形界面、收费模式、支持平台或效果指标等信息。