skill-host-compat

Skill Host Compatibility 是一个用于在提交技能 PR 前运行主机兼容性门禁的脚本，其检查逻辑与 CI 一致。该检查针对 Codex 和 Cursor 的技能副本，而非 Claude 专属的运行时质量。

用途

该工具用于在以下场景中激活：在 skills/ 下添加或编辑技能时；将技能复制到 .agents/skills/ 或 .cursor/skills/ 时；审查询问某技能是否可以安全安装到 Codex 或 Cursor 时；CI 报告 validate-skill-host-compat.js 发现的问题时。

主要能力

规范技能位于 skills/ 目录。Codex 加载 .agents/skills/，Cursor 加载较小的 .cursor/skills/ 子集。CONTRIBUTING 文档说明该同步为手动操作。validate-skills.js 仅检查 SKILL.md 是否存在以及 name/description 是否为可用的 YAML。tests/ci/codex-skill-surface.test.js 仅能看到 .agents/skills/。而本脚本是跨目录树的门禁，具体检查内容包括：

在 Codex/Cursor 投影中，可执行 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 默认行为保持不变（#1663）。

使用方式

从仓库根目录运行：

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

适用场景

适用于在 skills/ 下添加或编辑技能、将技能复制到 Codex 或 Cursor 目录、审查技能是否可安全安装到 Codex 或 Cursor，以及处理 CI 报告的主机兼容性发现时。

限制与反模式

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 查看清单警告数量而不使目录树失败。

技能介绍

用途