Skill Host Compat
Lint ECC skills for Codex/Cursor-safe frontmatter and Claude-only substitutions before a skill PR.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Skill Host Compat when an AI agent needs a reusable SKILL.md workflow for this job: Lint ECC skills for Codex/Cursor-safe frontmatter and Claude-only substitutions before a skill PR.
When not to use it
Skip Skill Host Compat when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/skill-host-compat # Save SKILL.md to ~/.claude/skills/skill-host-compat/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/skill-host-compat/SKILL.md. For a shared project, commit the folder at .claude/skills/skill-host-compat/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Skill Host Compat skill for this task: Use Skill Host Compat when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
73/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 76/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeinferred
The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- chatgptinferred
The skill text mentions ChatGPT or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# 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
Intended uses
- Use Skill Host Compat when this documented workflow matches the task.
Implementation notes
- 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
- Run this script before npm test when the change is a new skill.
- Use --inventory to see checklist warning volume without failing the tree.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.