skill-host-compat

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Host Compatibility

Skill 宿主兼容性

Run the same host-compat gate CI uses on

skills/

before opening a skill PR. The check is for Codex and Cursor copies, not Claude-only runtime quality.

在提交 Skill PR 前，对

skills/

运行与 CI 相同的宿主兼容性门禁。该检查针对 Codex 和 Cursor 副本，而非 Claude 专属的运行时质量。

When to Activate

激活时机

Adding or editing a skill under
```
skills/
```
Copying a skill into
```
.agents/skills/
```
or
```
.cursor/skills/
```
A review asks whether a skill is safe to install into Codex or Cursor
CI reports
```
validate-skill-host-compat.js
```
findings

在
```
skills/
```
下添加或编辑 Skill
将 Skill 复制到
```
.agents/skills/
```
或
```
.cursor/skills/
```
审查中有人询问某个 Skill 是否可安全安装到 Codex 或 Cursor
CI 报告
```
validate-skill-host-compat.js
```
检查结果

Core Concepts

核心概念

Canonical skills live in

skills/

. Codex loads

.agents/skills/

. Cursor loads a smaller

.cursor/skills/

subset. CONTRIBUTING documents that sync as manual.

validate-skills.js

only checks that

SKILL.md

exists and that

name

description

are usable YAML.

tests/ci/codex-skill-surface.test.js

only sees

.agents/skills/

. This script is the cross-tree gate:

Claude-only substitutions in executable
```
bash
```
/
```
sh
```
/
```
zsh
```
fences in Codex/Cursor projections (
```
${CLAUDE_SESSION_ID}
```
,
```
${CLAUDE_SKILL_DIR}
```
,
```
${CLAUDE_PLUGIN_ROOT}
```
,
```
${CLAUDE_PROJECT_DIR}
```
,
```
$ARGUMENTS
```
) fail. Codex leaves those tokens as literal text. In a Codex copy, rewrite
```
${CLAUDE_PROJECT_DIR}
```
to
```
$(pwd)
```
or an explicit path.
A Codex copy may only use
```
name
```
,
```
description
```
,
```
metadata
```
,
```
license
```
, and
```
allowed-tools
```
.
```
origin: ECC
```
may stay on the canonical
```
skills/
```
copy and must be stripped on the Codex copy.
A skill listed in
```
agents/openai.yaml
```
that has a
```
skills/
```
directory must have
```
.agents/skills/<name>/
```
. Cursor copies are optional; when present,
```
name:
```
must match the directory.
CONTRIBUTING checklist items (When to Activate, Anti-Patterns, name matches directory, 500/800 line caps) warn. They fail only with
```
--strict-checklist
```
.

validate-skills.js

frontmatter WARN default is unchanged (#1663).

权威 Skill 位于

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
```
。权威
```
skills/
```
副本可以保留
```
origin: ECC
```
，但 Codex 副本必须将其移除。
如果
```
agents/openai.yaml
```
中列出的某个 Skill 存在
```
skills/
```
目录，则必须同时存在
```
.agents/skills/<name>/
```
。Cursor 副本是可选的；存在时，其
```
name:
```
必须与目录名一致。
CONTRIBUTING 检查清单项目（激活时机、反模式、name 与目录名一致、500/800 行上限）会产生警告。仅在使用
```
--strict-checklist
```
时才会判定失败。

validate-skills.js

的 frontmatter WARN 默认行为保持不变（#1663）。

Code Examples

代码示例

From the repo root:

bash

node scripts/ci/validate-skill-host-compat.js

Print counts without failing:

bash

node scripts/ci/validate-skill-host-compat.js --inventory

Promote checklist warnings:

bash

node scripts/ci/validate-skill-host-compat.js --strict-checklist

Slash command:

/skill-host-compat
/skill-host-compat --inventory

从仓库根目录运行：

bash

node scripts/ci/validate-skill-host-compat.js

仅打印计数且不使检查失败：

bash

node scripts/ci/validate-skill-host-compat.js --inventory

将检查清单警告升级为失败：

bash

node scripts/ci/validate-skill-host-compat.js --strict-checklist

斜杠命令：

/skill-host-compat
/skill-host-compat --inventory

Anti-Patterns

反模式

Codex and Cursor projections must resolve Claude-only substitutions in executable blocks. Canonical Claude-scoped examples remain valid. POSIX

$1

and

${1}

parameters are ambiguous and require review rather than failing this gate. This fence is the forbidden pattern:

bash

echo "${CLAUDE_SESSION_ID}"
ls "${CLAUDE_SKILL_DIR}"
node "${CLAUDE_PLUGIN_ROOT}/scripts/setup.js" $ARGUMENTS
cd "${CLAUDE_PROJECT_DIR}"

Do not add

version:

origin:

to a Codex copy under

.agents/skills/

. Do not treat a passing

validate-skills.js

run as Codex-safe. Do not require every

skills/

entry to have a Cursor copy.

Codex 和 Cursor 投影必须在可执行代码块中解析仅限 Claude 使用的替换项。限定于 Claude 范围的权威示例仍然有效。POSIX

$1

和

${1}

参数含义不明确，需要人工审查，而不是由此门禁判定失败。以下代码围栏属于禁止模式：

bash

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-safe。不要要求每个

skills/

条目都存在对应的 Cursor 副本。

Best Practices

最佳实践

Keep canonical
```
origin: ECC
```
if the CONTRIBUTING template calls for it.
Drop
```
origin
```
,
```
version
```
, and
```
argument-hint
```
on the Codex copy.
Show host-portable commands in bash fences (
```
npx
```
,
```
ecc
```
, or a resolved root). Rewrite
```
${CLAUDE_PROJECT_DIR}
```
in Codex copies to
```
$(pwd)
```
or an explicit path. Keep valid Claude-scoped forms in canonical instructions; resolve host variables in the target projection.
Run this script before
```
npm test
```
when the change is a new skill.
Use
```
--inventory
```
to see checklist warning volume without failing the tree.

如果 CONTRIBUTING 模板要求使用，则在权威副本中保留
```
origin: ECC
```
。
从 Codex 副本中移除
```
origin
```
、
```
version
```
和
```
argument-hint
```
。
在 bash 代码围栏中展示跨宿主可移植的命令（
```
npx
```
、
```
ecc
```
或已解析的根路径）。在 Codex 副本中，将
```
${CLAUDE_PROJECT_DIR}
```
改写为
```
$(pwd)
```
或显式路径。在权威说明中保留有效的 Claude 专属形式；在目标投影中解析宿主变量。
新增 Skill 时，在运行
```
npm test
```
前先运行此脚本。
使用
```
--inventory
```
查看检查清单警告数量，且不会使整个目录树判定失败。

skill-host-compat

Original

Translation

Skill Host Compatibility

Skill 宿主兼容性

When to Activate

激活时机

Core Concepts

核心概念

Code Examples

代码示例

Anti-Patterns

反模式

Best Practices

最佳实践

Related Skills

相关 Skill