Skill Host Compatibility

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.

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

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).

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

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.

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.

Related Skills

```
skill-comply
```
— runtime behavioral traces, not host-portability
```
skill-stocktake
```
— holistic audit of installed
```
~/.claude/skills
```
```
skill-scout
```
— search existing skills before creating a new one

skill-host-compat

NPX Install

Tags

SKILL.md Content

Skill Host Compatibility

When to Activate

Core Concepts

Code Examples

Anti-Patterns

Best Practices

Related Skills