AIPM
Theme

AIPM package

Skill Host Compat

@affaan-m/skill-host-compat@1.0.0

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

Scanned · no issues · Nov 6, 2026

GitHub stars: ★ 298K

LinkedInPost

Install Skill

Pins this version in aipm.package.json and aipm-lock.json.

aipm add @affaan-m/skill-host-compat@1.0.0

Without project tracking

Writes the skill files only. Add --no-init to skip aipm.package.json and the lockfile.

aipm add @affaan-m/skill-host-compat@1.0.0 --no-init

How to use

Install the skill above, then run this in your AI tool:

/skill-host-compat <your description>

About

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.

Source

What gets added to your project

Preview every file this package writes on install before you run the command above.

Summary

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

Skill instructions

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:

code
/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

Loading package files…

Share this package

Add an Install with AIPM badge

Add this badge to a GitHub README so readers can open the package page and install the same version.

Install with AIPM
[![Install with AIPM](https://www.aipm-registry.com/install-with-aipm.svg)](https://www.aipm-registry.com/skills/affaan-m/skill-host-compat/1.0.0?utm_source=github&utm_medium=readme&utm_campaign=package_badge)

Publisher

Affaan Mustafa

This imported publisher has not claimed its AIPM account. A connected account confirms account control, but it does not guarantee that a package is safe.

AI assistant context

What this skill is for

@affaan-m/skill-host-compat@1.0.0 is an AIPM skill package for All tools. Use it when a project needs the reusable AI behavior described as: Lint ECC skills for Codex/Cursor-safe frontmatter and Claude-only substitutions before a skill PR.

Install
aipm add @affaan-m/skill-host-compat@1.0.0
Use after install
/skill-host-compat <your description>

Tool targets

Install command by target

Add --no-init to any of these when you want the skill files without aipm.package.json or aipm-lock.json.

cursor

Run this variant when you want to install the package into cursor.

aipm add @affaan-m/skill-host-compat@1.0.0 --target cursor --ci

claude

Run this variant when you want to install the package into claude.

aipm add @affaan-m/skill-host-compat@1.0.0 --target claude --ci

Discussion

Comments (0)

Loading comments…

Keep exploring

Affaan Mustafa/ui-canvas

Preview a UI component mockup in a local browser canvas where the human directly edits it (move, resize, edit text, delete, restyle), switches mobile/desktop/custom viewports, tests it, chats with you, and clicks Save and Finish. You the...

Published by Affaan Mustafa

skillScanned · no issues★ 308KImported · UnverifiedAll toolsNov 21, 2026, 1:11 AM6.61 KBMIT

Affaan Mustafa/yoruba-localization-testing

Test Yoruba (yo) and English bilingual interfaces for tone marks, underdots, Unicode normalization, translation fallback, and accessibility.

Published by Affaan Mustafa

skillScanned · no issues★ 306KImported · UnverifiedAll toolsNov 18, 2026, 1:19 AM3.43 KBMIT

Affaan Mustafa/web-perimeter-owasp-2025-audit

Passive, non-destructive web perimeter security auditing mapped to OWASP Top 10:2025 surface leads, CDN Unkeyed Header Web Cache Poisoning (X-Forwarded-Host), supply chain manifest exposure, git object dumping prevention (/.git/HEAD), cr...

Published by Affaan Mustafa

skillScanned · flagged★ 305KImported · UnverifiedAll toolsNov 17, 2026, 1:13 AM8.86 KBMIT

Package FAQ

Install and compatibility

How to install
Run aipm add @affaan-m/skill-host-compat@1.0.0 in a project that has AIPM initialized.
Supported tools
@affaan-m/skill-host-compat@1.0.0 supports All tools.

Before installing

AIPM skills can add files to your project. Review the package name, target, description, license, and publisher before installing. Use a clean branch when trying a new skill.