skill-host-compat

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:

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

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

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

1. 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:

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

Print counts without failing:

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

Promote checklist warnings:

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:

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

Do not add version: or 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