Skip to main content
Agent skill

Skill Host Compat

Lint ECC skills for Codex/Cursor-safe frontmatter and Claude-only substitutions before a skill PR.

Get started

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?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/skill-host-compat
# Save SKILL.md to ~/.claude/skills/skill-host-compat/SKILL.md
  1. 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.
  2. 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.
  3. 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.

Starter prompt
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.