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. 2. 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. 3. 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. 4. 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:` 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