Guide · Agent skill

How to use the Skill Host Compatibility Linter agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

skill-host-compat is an agent skill that tells Claude how to run a compatibility check on skill files before they are submitted to the ECC project. It targets copies meant for Codex and Cursor, which can break when they contain Claude-only variables or frontmatter fields. This guide explains what the skill does, how to install it, how to trigger it, and how to read and fix its findings.

Skill Host Compatibility Linteraffaan-m/ECC · MIT Download the skill

Quick start

1Download and unzip. Download the ZIP from this page and unzip it so you have a skill-host-compat folder containing SKILL.md and agents/openai.yaml.
2Install the skill. Place the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
3Get a local ECC checkout. Clone or open the ECC repository and confirm that scripts/ci/validate-skill-host-compat.js exists at the repo root.
4Ask for the check. Ask Claude to run the host compatibility check on the skill files you are changing, or use the $skill-host-compat command.
5Run the script. From the repo root, run node scripts/ci/validate-skill-host-compat.js, adding --inventory for counts only or --strict-checklist to fail on checklist warnings.
6Fix the findings. Rewrite Claude-only variables in Codex and Cursor copies and remove origin, version and argument-hint from the Codex copy, then re-run the check.

What does the skill make the agent do?

The skill runs the same host-compatibility gate that CI runs on the skills/ directory of the ECC repository. It checks for two main problems: Claude-only substitutions in executable bash, sh or zsh blocks, and frontmatter fields that a Codex copy should not contain.

When a check fails, the skill also explains how to fix it. For example, a Codex copy should rewrite $CLAUDE_PROJECT_DIR to $(pwd) or an explicit path, because Codex leaves that token as literal text. The skill is about Codex and Cursor copies, not about how well a skill performs in Claude.

Flags Claude-only variables such as $CLAUDE_SESSION_ID, $CLAUDE_SKILL_DIR, $CLAUDE_PLUGIN_ROOT, $CLAUDE_PROJECT_DIR and $ARGUMENTS in executable shell fences
Flags Codex copies that use fields other than name, description, metadata, license and allowed-tools, such as origin, version or argument-hint
Checks that a skill listed in agents/openai.yaml has a matching .agents/skills/<name>/ directory
Reports CONTRIBUTING checklist items as warnings unless strict mode is used

How do you install the skill?

Download the ZIP file from this page and unzip it. The skill folder contains SKILL.md and agents/openai.yaml. Put the folder in one of these locations:

Personal skills: ~/.claude/skills/
A single project: the .claude/skills/ folder inside that project
Claude apps: upload the ZIP under Settings → Capabilities → Skills

How do you trigger the skill with a request?

You do not need a special command. Ask in plain language, and mention the ECC skill files you are working on. The source also lists a slash command, $skill-host-compat, which runs the check, and $skill-host-compat --inventory, which prints counts without failing.

Check whether this skill is safe to copy into Codex or Cursor
Run the host compatibility check on my new skill before I open the PR
CI is reporting validate-skill-host-compat.js findings. What do they mean and how do I fix them?
Convert this skill's Codex copy so it does not use $CLAUDE_PROJECT_DIR

$skill-host-compat
$skill-host-compat --inventory

How do you run the check yourself?

Run these commands from the root of a local ECC checkout. The script must be present at scripts/ci/validate-skill-host-compat.js. Use --inventory to see how many checklist warnings there are without failing the tree, and --strict-checklist to turn those warnings into failures.

The source recommends running this script before npm test when the change adds a new skill.

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

How do you fix the findings?

Keep valid Claude-scoped forms in the canonical skills/ copy. Resolve host variables only in the Codex or Cursor copy. Use host-portable commands such as npx, ecc or a resolved root path in bash fences.

The skill also notes that POSIX $1 and ${1} parameters are ambiguous, so they are flagged for review rather than failing the gate.

In a Codex copy, change cd "$CLAUDE_PROJECT_DIR" to cd "$(pwd)" or an explicit path
Remove origin, version and argument-hint from the Codex copy under .agents/skills/
Keep origin: ECC on the canonical copy if the CONTRIBUTING template calls for it
Do not treat a passing validate-skills.js run as proof that a skill is Codex-safe

cd "$(pwd)"

What does it need, and what are the safety notes?

You need Node.js, because the scripts are run with node. You also need a local checkout of the ECC repository that contains scripts/ci/validate-skill-host-compat.js, and npm if you plan to run npm test afterwards. The skill runs scripts, so review them before running. The listing says it does not use the network.

The script path and directory layout are specific to the ECC repository. The files do not show that the skill works in other projects.

Requires Node.js and npm
Requires a local ECC checkout with the validation script present
Runs scripts locally; the listing says it makes no network calls
Not for Claude-only use: the checks do not change Claude behaviour

What people use it for

Checking a new ECC skill before opening a pull request
Reviewing whether an existing skill is safe to copy into .agents/skills/ for Codex
Understanding a failing validate-skill-host-compat.js job in CI and fixing the flagged lines
Counting checklist warnings across the tree with --inventory before a larger cleanup

Frequently asked questions

Is the skill-host-compat skill free?

The skill is listed under the MIT licence. The source does not mention prices or paid tiers, so check the licence file in the ECC repository for the terms.

What are the requirements to run skill-host-compat?

You need Node.js, npm if you run npm test, and a local checkout of the ECC repository that contains scripts/ci/validate-skill-host-compat.js. The listing says it does not use the network.

Where do I install an agent skill?

For personal use, place the skill folder in ~/.claude/skills/. For one project, place it in that project's .claude/skills/ folder. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.

Why does the check say $CLAUDE_PROJECT_DIR fails?

Codex leaves Claude-only variables such as $CLAUDE_PROJECT_DIR as literal text instead of replacing them. In a Codex copy, rewrite it to $(pwd) or an explicit path.

Does a passing check mean my skill is fully correct for Codex?

No. The SKILL.md warns that a passing validate-skills.js run is not proof of Codex safety, and the host-compat check only covers the specific rules it tests.

Can I use skill-host-compat outside the ECC project?

The source says the script path and directory layout are specific to ECC, and the files do not show it is portable to other repositories. Related skills include skill-comply, skill-stocktake and skill-scout, which cover runtime traces, auditing installed skills and searching existing skills.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you contribute to the ECC repository or maintain Codex and Cursor copies of its skills, and want to catch host-specific problems before a pull request. Skip it if you only run skills in Claude, or if you work in a project outside ECC, since the checks do not affect Claude behaviour and the script is tied to ECC's layout.

Download the skill