---
name: skill-host-compat
description: Lint ECC skills for Codex/Cursor-safe frontmatter and Claude-only substitutions before a skill PR.
---

# 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
   (`$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; do not use these unresolved projection examples:

```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