AGENT SKILL

skill-host-compat

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

License 许可
MIT
最近更新
2026-11-11
Stars
★ 3
Forks
0

01 前言 Front Matter

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

03 SKILL.md 正文

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:

node scripts/ci/validate-skill-host-compat.js

Print counts without failing:

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

Promote checklist warnings:

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:

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

04 同仓库更多 Skills

mdnaimul22
mdnaimul22/human-skills

system-lifecycle-designer

Universal architectural methodology for designing granular, atomic, and sub-atomic lifecycles and end-to-end workflows for single functionality integrations across any domain (daemons, batch jobs, request transactions, resource pools). Provides patterns for deterministic identity, pre-commit validation, differential reconciliation, sticky leasing, state machines, transactional persistence, and closed-loop feedback.

★ 3
mdnaimul22
mdnaimul22/human-skills

style-sampling

Make a new episode in a proven video style - Collage Explainer, Finance Explainer, Animated Science Explainer, 3D Brand Explainer, 3D True Crime - on the person's topic. Use for "an episode of", "in the style of", "sample this style", 「用这个风格做一集」. One video to copy is reverse-any-video.

★ 3
mdnaimul22
mdnaimul22/human-skills

reverse-any-video

Rebuild any video file as an editable HyperFrames project - motion graphics, talking heads, live action or AI-generated footage - checked against the original frame by frame. Use to reverse, recreate, remake, replicate or copy a video, or 「复刻这个视频」「照着这个视频做一个」.

★ 3
mdnaimul22
mdnaimul22/human-skills

typescript-patterns

TypeScript patterns for strict, type-safe, maintainable code in modern TypeScript and JavaScript applications. Covers strict compiler configuration, type design, narrowing, discriminated unions, generics, async and error handling, module boundaries, dependency hygiene, and type-level testing. Use when writing or reviewing TypeScript or JavaScript code.

★ 3
mdnaimul22
mdnaimul22/human-skills

test-collaboration

Inventory and govern a project's test assets. Connect requirements, business rules, risks, bugs, and cross-boundary contracts to stable TEST-IDs and executable evidence in the repository's existing test registry or TESTS.md. Use for test inventory, test gap analysis, unit/integration/contract/E2E/smoke classification, bug-to-test regression protection, consumer/provider contract testing, test-necessity review, and pre-delivery evidence review.

★ 3
mdnaimul22
mdnaimul22/human-skills

story-lifecycle

Manage a file-based epic → story → sprint development loop without requiring an external project management tool. Creates and tracks epics, breaks them into user stories, assigns them to sprints, and drives implementation story by story. Use when starting a new feature initiative or when the team has no Jira/Linear/Taiga but needs structured delivery tracking.

★ 3