Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

fix(skills): scope host compatibility to target projections

haelyra9d09febe5ddc
diff --cc .agents/skills/skill-host-compat/SKILL.md
index 000000000,d790a56ed..3805b4607
mode 000000,100644..100644
--- a/.agents/skills/skill-host-compat/SKILL.md
+++ b/.agents/skills/skill-host-compat/SKILL.md
@@@ -1,0 -1,102 +1,101 @@@
+ ---
+ name: skill-host-compat
+ description: Lint ECC skills for Codex/Cursor-safe frontmatter and Claude-only substitutions before a skill PR.
+ ---
+
+ # 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
+ (`$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
+
-Do not put Claude-only substitutions in bash blocks. This fence is the
-forbidden pattern:
++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; do not use these unresolved projection examples:
+
+ ```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. Mention other Claude env vars in prose, not in executable
- fences.
++ 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
diff --cc README.md
index 507b2fb3b,e41e18848..32b5a1b2b
--- a/README.md
+++ b/README.md
@@@ -138,9 -138,9 +138,9 @@@ Instead of rebuilding that process in e
> Optimize the context window. Persist everything else.
-ECC is MIT-licensed open source. It works best with Claude Code today, has a supported Codex sync path, and provides capability-limited adapters for Cursor, OpenCode, Gemini, Zed, GitHub Copilot, Antigravity, Qwen, and other harnesses. See the [support status matrix](#platform-support) before assuming feature parity.
+ECC is MIT-licensed open source. It works best with Claude Code today, has native Codex and Qoder plugin paths, and provides capability-limited adapters for Cursor, OpenCode, Gemini, Zed, GitHub Copilot, Antigravity, Qwen, and other harnesses. See the [support status matrix](#platform-support) before assuming feature parity.
- Access to 71 agents, 302 skills, and 95 legacy command shims, plus hooks, rules, memory, continuous learning, and AgentShield security scanning. The agents are specialized for planning, review, build repair, security, architecture, and domain work.
+ Access to 71 agents, 303 skills, and 96 legacy command shims, plus hooks, rules, memory, continuous learning, and AgentShield security scanning. The agents are specialized for planning, review, build repair, security, architecture, and domain work.
| Included | Count | What it gives you |
| ---------------- | ----------: | ------------------------------------------------------------------------------------ |
diff --cc commands/skill-host-compat.md
index 000000000,c9ebab928..e3abc77f4
mode 000000,100644..100644
--- a/commands/skill-host-compat.md
+++ b/commands/skill-host-compat.md
@@@ -1,0 -1,40 +1,40 @@@
+ ---
+ name: skill-host-compat
+ description: Lint ECC skills for Codex/Cursor-safe frontmatter and Claude-only substitutions before a skill PR.
+ command: true
+ ---
+
+ # Skill Host Compatibility
+
+ Lint curated `skills/` for Codex-safe frontmatter and Claude-only substitutions.
+
+ ## Implementation
+
+ Run the host-compat validator:
+
+ ```bash
+ ECC_ROOT="${CLAUDE_PLUGIN_ROOT:-$(node -e "var r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();console.log(r)}")}"
+ node "$ECC_ROOT/scripts/ci/validate-skill-host-compat.js"
+ ```
+
+ Inventory counts without failing:
+
+ ```bash
+ ECC_ROOT="${CLAUDE_PLUGIN_ROOT:-$(node -e "var r=(function(){var p=require('path'),f=require('fs'),o=require('os');var e=process.env.CLAUDE_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var d=p.join(o.homedir(),'.claude');function L(x){try{return require(p.join(x,'scripts','lib','resolve-ecc-root')).resolveEccRoot()}catch(_){return null}}var r=L(d);if(r)return r;var s=['ecc','ecc@ecc','marketplaces/ecc','everything-claude-code','everything-claude-code@everything-claude-code','marketplaces/everything-claude-code'];for(var i=0;i<s.length;i++){r=L(p.join(d,'plugins',s[i]));if(r)return r}try{var g=['ecc','everything-claude-code'];for(var j=0;j<g.length;j++){var c=p.join(d,'plugins','cache',g[j]);var O=f.readdirSync(c);for(var k=0;k<O.length;k++){var q=p.join(c,O[k]);var V=f.readdirSync(q);for(var m=0;m<V.length;m++){r=L(p.join(q,V[m]));if(r)return r}}}}catch(_){}return d})();console.log(r)}")}"
+ node "$ECC_ROOT/scripts/ci/validate-skill-host-compat.js" --inventory
+ ```
+
+ ## Usage
+
+ ```
+ /skill-host-compat # Fail on substitutions and Codex drift
+ /skill-host-compat --inventory # JSON counts, exit 0
+ /skill-host-compat --strict-checklist
+ ```
+
+ ## What to Do
+
+ 1. Run `scripts/ci/validate-skill-host-compat.js` from the ECC root
+ 2. Show ERROR and WARN lines to the user
-3. For substitution errors, move Claude env vars out of bash fences. Rewrite `$CLAUDE_PROJECT_DIR` to `$(pwd)` or an explicit path
++3. For substitution errors, resolve Claude env vars in the affected Codex/Cursor projection. Rewrite `$CLAUDE_PROJECT_DIR` to `$(pwd)` or an explicit path
+ 4. For Codex-key errors, drop `origin` / `version` / `argument-hint` on the copy
diff --cc manifests/context-packs/[email protected]
index 152abae64,fb14723ff..74134f94d
--- a/manifests/context-packs/[email protected]
+++ b/manifests/context-packs/[email protected]
@@@ -1,288 -1,1 +1,288 @@@
-{"coverage":{"skills":303,"withTriggers":32},"generatedAt":"2026-09-24T23:51:22.784Z","id":"skill-triggers@1","model":{"effort":null,"id":"hand-seeded","source":"manual-curation-pending-regeneration"},"registryDigest":"162a7d6cfe4d629eab7e1e0527c98005e226f3495a09b5d523cdaa13d61f945e","schemaVersion":1,"triggers":{"skill:api-connector-builder":["add api integration","new provider connector","match existing integration pattern"],"skill:api-design":["rest endpoint design","pagination api","status codes","api versioning","rate limiting api","resource naming","filtering api","api error responses","offset pagination","limit query parameter","pagination defaults"],"skill:backend-patterns":["express api","node backend architecture","nextjs api routes","server side patterns","data access layer","static file server","url path handling","file server"],"skill:browser-qa":["deployed feature test","visual regression screenshots","core web vitals check","axe accessibility audit","ship do not ship","staging verification"],"skill:canary-watch":["post deploy monitoring","smoke test url","production url check","console errors production","sse stream check","after deploy verification"],"skill:code-tour":["onboarding walkthrough","explain subsystem","architecture tour","pr walkthrough","rca tour"],"skill:coding-standards":["code review standards","naming conventions","readability review","immutability conventions","fix naming typo","export naming","consistent exports"],"skill:content-hash-cache-pattern":["cache file processing","content addressed cache","sha256 hash cache"],"skill:database-migrations":["zero downtime migration","schema change production","add column large table","backfill data","expand contract","concurrent index","migration rollback","prisma migration","django migration"],"skill:deployment-patterns":["ci cd setup","dockerize app","health checks","rollback strategy","production readiness","deploy pipeline","containerize application"],"skill:design-system":["design tokens","visual consistency audit","css custom properties","ui audit","design system bootstrap"],"skill:django-patterns":["django orm","drf api","django rest framework","django caching","django signals","django middleware"],"skill:django-security":["django authentication","csrf protection","sql injection prevention","xss prevention","django deployment security","role based access control","authorization middleware","permissions checks"],"skill:docker-patterns":["dockerfile review","docker compose setup","container security","multi service orchestration"],"skill:error-handling":["error types","retry logic","circuit breaker","user facing errors","exception handling patterns","typed errors","error boundaries","go error handling","custom error class","error codes","config validation"],"skill:evm-token-decimals":["token decimals","wei conversion","erc20 balance off","bridge token precision"],"skill:frontend-a11y":["aria attributes","screen reader support","focus management","semantic html","form labeling","keyboard navigation react","a11y lint errors"],"skill:git-workflow":["merge vs rebase","commit conventions","resolve merge conflict","branching strategy","clean up commits","pull request cleanup","git history tidy"],"skill:hexagonal-architecture":["ports and adapters","dependency injection boundaries","decouple domain from io"],"skill:kubernetes-patterns":["kubernetes manifests","kubectl debugging","pod probes","k8s rbac","autoscaling config","configmap secrets"],"skill:orch-fix-defect":["fix a bug","broken behavior","regression fix","reproduce bug","defect repair"],"skill:postgres-patterns":["slow postgres query","query optimization","index design","rls policies","supabase schema","postgres indexing","database performance","schema design postgres","postgres driver","node postgres","query planner"],"skill:python-patterns":["pythonic code","pep 8","type hints python","python code review","idiomatic python"],"skill:python-testing":["pytest fixtures","mocking python","parametrized tests","coverage python","tdd python"],"skill:redis-patterns":["cache aside pattern","distributed lock","redis rate limiting","cache invalidation"],"skill:regex-vs-llm-structured-text":["parse invoice","extract receipt data","text extraction pipeline","parse form fields","cheap document parser","extract table data","parse log lines","parse access logs","common log format","log line parsing"],"skill:rust-patterns":["rust ownership","borrow checker","rust error handling","traits rust","rust concurrency","idiomatic rust"],"skill:search-first":["find existing library","npm package research","before writing custom code","evaluate existing tools","add dependency research"],"skill:security-review":["security audit","authentication review","sanitize user input","secrets handling","payment security checklist","prevent injection attacks","secure api endpoints","authn authz review","vulnerability checklist","input validation security","parameterized queries","sql injection"],"skill:security-scan":["audit claude config","claudemd security","mcp server audit","agentshield scan","hook configuration audit","settings json security"],"skill:tdd-workflow":["write test first","failing test","red green refactor","test driven development","regression test first","write a regression test"],"skill:verification-loop":["pre pr checks","verification report","quality gates","build lint test coverage","before creating a pr"]},"triggersDigest":"25b97a9e06fc336c7cf95ab854ed1a41033a54bcd6e1fb1cf69dc906332462aa"}
+{
+ "coverage": {
+ "skills": 302,
+ "withTriggers": 32
+ },
+ "generatedAt": "2026-09-24T23:51:22.784Z",
+ "id": "skill-triggers@1",
+ "model": {
+ "effort": null,
+ "id": "hand-seeded",
+ "source": "manual-curation-pending-regeneration"
+ },
- "registryDigest": "1d84b5f3852a014edbaa36c038561382f6e11b7b69a011d8801c7b8abd22fbb7",
++ "registryDigest": "577a749c4ea19a03c2cd5263f1b1797cc45d395cae2b934b307c912bb2a97059",
+ "schemaVersion": 1,
+ "triggers": {
+ "skill:api-connector-builder": [
+ "add api integration",
+ "new provider connector",
+ "match existing integration pattern"
+ ],
+ "skill:api-design": [
+ "rest endpoint design",
+ "pagination api",
+ "status codes",
+ "api versioning",
+ "rate limiting api",
+ "resource naming",
+ "filtering api",
+ "api error responses",
+ "offset pagination",
+ "limit query parameter",
+ "pagination defaults"
+ ],
+ "skill:backend-patterns": [
+ "express api",
+ "node backend architecture",
+ "nextjs api routes",
+ "server side patterns",
+ "data access layer",
+ "static file server",
+ "url path handling",
+ "file server"
+ ],
+ "skill:browser-qa": [
+ "deployed feature test",
+ "visual regression screenshots",
+ "core web vitals check",
+ "axe accessibility audit",
+ "ship do not ship",
+ "staging verification"
+ ],
+ "skill:canary-watch": [
+ "post deploy monitoring",
+ "smoke test url",
+ "production url check",
+ "console errors production",
+ "sse stream check",
+ "after deploy verification"
+ ],
+ "skill:code-tour": [
+ "onboarding walkthrough",
+ "explain subsystem",
+ "architecture tour",
+ "pr walkthrough",
+ "rca tour"
+ ],
+ "skill:coding-standards": [
+ "code review standards",
+ "naming conventions",
+ "readability review",
+ "immutability conventions",
+ "fix naming typo",
+ "export naming",
+ "consistent exports"
+ ],
+ "skill:content-hash-cache-pattern": [
+ "cache file processing",
+ "content addressed cache",
+ "sha256 hash cache"
+ ],
+ "skill:database-migrations": [
+ "zero downtime migration",
+ "schema change production",
+ "add column large table",
+ "backfill data",
+ "expand contract",
+ "concurrent index",
+ "migration rollback",
+ "prisma migration",
+ "django migration"
+ ],
+ "skill:deployment-patterns": [
+ "ci cd setup",
+ "dockerize app",
+ "health checks",
+ "rollback strategy",
+ "production readiness",
+ "deploy pipeline",
+ "containerize application"
+ ],
+ "skill:design-system": [
+ "design tokens",
+ "visual consistency audit",
+ "css custom properties",
+ "ui audit",
+ "design system bootstrap"
+ ],
+ "skill:django-patterns": [
+ "django orm",
+ "drf api",
+ "django rest framework",
+ "django caching",
+ "django signals",
+ "django middleware"
+ ],
+ "skill:django-security": [
+ "django authentication",
+ "csrf protection",
+ "sql injection prevention",
+ "xss prevention",
+ "django deployment security",
+ "role based access control",
+ "authorization middleware",
+ "permissions checks"
+ ],
+ "skill:docker-patterns": [
+ "dockerfile review",
+ "docker compose setup",
+ "container security",
+ "multi service orchestration"
+ ],
+ "skill:error-handling": [
+ "error types",
+ "retry logic",
+ "circuit breaker",
+ "user facing errors",
+ "exception handling patterns",
+ "typed errors",
+ "error boundaries",
+ "go error handling",
+ "custom error class",
+ "error codes",
+ "config validation"
+ ],
+ "skill:evm-token-decimals": [
+ "token decimals",
+ "wei conversion",
+ "erc20 balance off",
+ "bridge token precision"
+ ],
+ "skill:frontend-a11y": [
+ "aria attributes",
+ "screen reader support",
+ "focus management",
+ "semantic html",
+ "form labeling",
+ "keyboard navigation react",
+ "a11y lint errors"
+ ],
+ "skill:git-workflow": [
+ "merge vs rebase",
+ "commit conventions",
+ "resolve merge conflict",
+ "branching strategy",
+ "clean up commits",
+ "pull request cleanup",
+ "git history tidy"
+ ],
+ "skill:hexagonal-architecture": [
+ "ports and adapters",
+ "dependency injection boundaries",
+ "decouple domain from io"
+ ],
+ "skill:kubernetes-patterns": [
+ "kubernetes manifests",
+ "kubectl debugging",
+ "pod probes",
+ "k8s rbac",
+ "autoscaling config",
+ "configmap secrets"
+ ],
+ "skill:orch-fix-defect": [
+ "fix a bug",
+ "broken behavior",
+ "regression fix",
+ "reproduce bug",
+ "defect repair"
+ ],
+ "skill:postgres-patterns": [
+ "slow postgres query",
+ "query optimization",
+ "index design",
+ "rls policies",
+ "supabase schema",
+ "postgres indexing",
+ "database performance",
+ "schema design postgres",
+ "postgres driver",
+ "node postgres",
+ "query planner"
+ ],
+ "skill:python-patterns": [
+ "pythonic code",
+ "pep 8",
+ "type hints python",
+ "python code review",
+ "idiomatic python"
+ ],
+ "skill:python-testing": [
+ "pytest fixtures",
+ "mocking python",
+ "parametrized tests",
+ "coverage python",
+ "tdd python"
+ ],
+ "skill:redis-patterns": [
+ "cache aside pattern",
+ "distributed lock",
+ "redis rate limiting",
+ "cache invalidation"
+ ],
+ "skill:regex-vs-llm-structured-text": [
+ "parse invoice",
+ "extract receipt data",
+ "text extraction pipeline",
+ "parse form fields",
+ "cheap document parser",
+ "extract table data",
+ "parse log lines",
+ "parse access logs",
+ "common log format",
+ "log line parsing"
+ ],
+ "skill:rust-patterns": [
+ "rust ownership",
+ "borrow checker",
+ "rust error handling",
+ "traits rust",
+ "rust concurrency",
+ "idiomatic rust"
+ ],
+ "skill:search-first": [
+ "find existing library",
+ "npm package research",
+ "before writing custom code",
+ "evaluate existing tools",
+ "add dependency research"
+ ],
+ "skill:security-review": [
+ "security audit",
+ "authentication review",
+ "sanitize user input",
+ "secrets handling",
+ "payment security checklist",
+ "prevent injection attacks",
+ "secure api endpoints",
+ "authn authz review",
+ "vulnerability checklist",
+ "input validation security",
+ "parameterized queries",
+ "sql injection"
+ ],
+ "skill:security-scan": [
+ "audit claude config",
+ "claudemd security",
+ "mcp server audit",
+ "agentshield scan",
+ "hook configuration audit",
+ "settings json security"
+ ],
+ "skill:tdd-workflow": [
+ "write test first",
+ "failing test",
+ "red green refactor",
+ "test driven development",
+ "regression test first",
+ "write a regression test"
+ ],
+ "skill:verification-loop": [
+ "pre pr checks",
+ "verification report",
+ "quality gates",
+ "build lint test coverage",
+ "before creating a pr"
+ ]
+ },
+ "triggersDigest": "25b97a9e06fc336c7cf95ab854ed1a41033a54bcd6e1fb1cf69dc906332462aa"
+}
diff --cc scripts/ci/validate-skill-host-compat.js
index 000000000,8dfc3a980..e346184b8
mode 000000,100644..100644
--- a/scripts/ci/validate-skill-host-compat.js
+++ b/scripts/ci/validate-skill-host-compat.js
@@@ -1,0 -1,509 +1,487 @@@
+ #!/usr/bin/env node
+ /**
+ * Lint curated skills for host-portable frontmatter and substitutions.
+ *
+ * Checks:
- * 1. Claude-only substitutions in executable bash/sh/zsh fences
++ * 1. Claude-only substitutions in Codex/Cursor executable bash/sh/zsh fences
+ * (${CLAUDE_SESSION_ID}, ${CLAUDE_SKILL_DIR}, ${CLAUDE_PLUGIN_ROOT},
+ * ${CLAUDE_PROJECT_DIR}, $ARGUMENTS). Codex and a bare shell leave
+ * those tokens literal. Rewrite ${CLAUDE_PROJECT_DIR} in Codex copies
+ * to $(pwd) or an explicit path.
+ * 2. Codex-copy frontmatter allowlist on .agents/skills/<name>/SKILL.md
+ * (name, description, metadata, license, allowed-tools). origin/version
+ * may remain on the canonical skills/ copy.
+ * 3. Subset drift: agents/openai.yaml names a skill that is missing from
+ * .agents/skills/, or a Codex/Cursor copy name: does not match its
+ * directory.
+ * 4. CONTRIBUTING checklist (WARN unless --strict-checklist): When to
+ * Activate, Anti-Patterns, name matches directory, 500/800 line caps.
+ *
+ * Default invocation is fail-closed on (1)-(3). Pass --inventory to print
+ * JSON counts and exit 0. Do not flip validate-skills.js to --strict;
+ * that file's WARN default is load-bearing for #1663.
+ *
- * Scope: curated skills/ plus Codex/Cursor copies. If skills/ is absent,
++ * Scope: canonical checklist plus host-specific Codex/Cursor projections.
++ * POSIX positional parameters ($1, ${1}) are ambiguous and never fail this gate. If skills/ is absent,
+ * exit 0 (nothing to validate).
+ */
+
+ 'use strict';
+
+ const fs = require('fs');
+ const path = require('path');
+
+ const { extractFrontmatter, inspectFrontmatter } = require('./validate-skills');
+
+ const DEFAULT_ROOT = path.join(__dirname, '../..');
+
+ const ALLOWED_CODEX_FRONTMATTER_KEYS = new Set([
+ 'allowed-tools',
+ 'description',
+ 'license',
+ 'metadata',
+ 'name',
+ ]);
+
+ const CLAUDE_SUBSTITUTION_PATTERNS = [
+ { token: '${CLAUDE_SESSION_ID}', regex: /\$\{CLAUDE_SESSION_ID\}/g },
+ { token: '$CLAUDE_SESSION_ID', regex: /\$CLAUDE_SESSION_ID\b/g },
+ { token: '${CLAUDE_SKILL_DIR}', regex: /\$\{CLAUDE_SKILL_DIR\}/g },
+ { token: '$CLAUDE_SKILL_DIR', regex: /\$CLAUDE_SKILL_DIR\b/g },
+ { token: '${CLAUDE_PLUGIN_ROOT}', regex: /\$\{CLAUDE_PLUGIN_ROOT\}/g },
+ { token: '$CLAUDE_PLUGIN_ROOT', regex: /\$CLAUDE_PLUGIN_ROOT\b/g },
+ { token: '${CLAUDE_PROJECT_DIR}', regex: /\$\{CLAUDE_PROJECT_DIR\}/g },
+ { token: '$CLAUDE_PROJECT_DIR', regex: /\$CLAUDE_PROJECT_DIR\b/g },
+ { token: '$ARGUMENTS', regex: /\$ARGUMENTS\b|\$\{ARGUMENTS\}/g },
- // Claude skill form ${1}. Bare $1 is handled in findSubstitutionTokens so
- // POSIX `VAR=$1` and Perl/awk `$1 < 80` are not treated as Claude args.
- { token: '$1', regex: /\$\{1\}|(?<![\w$])\$1(?!\d)/g },
++
+ ];
+
+ const EXECUTABLE_FENCE_LANGS = new Set(['bash', 'sh', 'zsh']);
+ const CHECKLIST_CODES = new Set([
+ 'missing-when-to-activate',
+ 'missing-anti-patterns',
+ 'name-mismatch',
+ 'line-cap-500',
+ 'line-cap-800',
+ ]);
+
+ function parseArgs(argv) {
+ const args = {
+ root: DEFAULT_ROOT,
+ inventory: false,
+ strictChecklist: false,
+ };
+
+ for (let i = 0; i < argv.length; i += 1) {
+ const arg = argv[i];
+ if (arg === '--inventory') {
+ args.inventory = true;
+ } else if (arg === '--strict-checklist') {
+ args.strictChecklist = true;
+ } else if (arg === '--root') {
+ const value = argv[i + 1];
+ if (!value) {
+ throw new Error('--root requires a directory path');
+ }
+ args.root = value;
+ i += 1;
+ }
+ }
+
+ return args;
+ }
+
+ function listSkillDirs(dir) {
+ if (!fs.existsSync(dir)) return [];
+ return fs.readdirSync(dir, { withFileTypes: true })
+ .filter(entry => entry.isDirectory() && !entry.name.startsWith('.'))
+ .map(entry => entry.name)
+ .sort();
+ }
+
+ function readFileIfPresent(filePath) {
+ if (!fs.existsSync(filePath)) return null;
+ return fs.readFileSync(filePath, 'utf8');
+ }
+
+ function unquoteYamlScalar(value) {
+ if (value === undefined || value === null) return '';
+ const trimmed = String(value).trim();
+ if (
+ (trimmed.startsWith('"') && trimmed.endsWith('"'))
+ || (trimmed.startsWith("'") && trimmed.endsWith("'"))
+ ) {
+ return trimmed.slice(1, -1);
+ }
+ return trimmed;
+ }
+
+ function extractTopLevelList(yamlSource, key) {
+ const lines = String(yamlSource).replace(/^\uFEFF/, '').split(/\r?\n/);
+ const results = [];
+ let collecting = false;
+
+ for (const line of lines) {
+ if (!collecting) {
+ if (line.trim() === `${key}:`) {
+ collecting = true;
+ }
+ continue;
+ }
+
+ if (/^[A-Za-z0-9_-]+:\s*/.test(line)) {
+ break;
+ }
+
+ const match = line.match(/^\s*-\s+(.+?)\s*$/);
+ if (match) {
+ results.push(unquoteYamlScalar(match[1]));
+ }
+ }
+
+ return results;
+ }
+
+ function listOpenaiYamlSkills(root) {
+ const filePath = path.join(root, 'agents', 'openai.yaml');
+ const source = readFileIfPresent(filePath);
+ if (source === null) return [];
+ return extractTopLevelList(source, 'skills');
+ }
+
+ function stripFrontmatter(content) {
+ const fm = extractFrontmatter(content);
+ if (!fm.present) {
+ return { frontmatter: fm, body: content.replace(/^\uFEFF/, ''), bodyOffset: 0 };
+ }
+ const match = content.replace(/^\uFEFF/, '').match(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/);
+ const bodyOffset = match ? match[0].length : 0;
+ return {
+ frontmatter: fm,
+ body: content.replace(/^\uFEFF/, '').slice(bodyOffset),
+ bodyOffset,
+ };
+ }
+
+ function findExecutableFences(body) {
+ const fences = [];
+ const fenceRe = /^```([^\r\n]*)\r?\n([\s\S]*?)^```[ \t]*(?:\r?\n|$)/gm;
+ let match = fenceRe.exec(body);
+ while (match) {
+ const info = (match[1] || '').trim();
+ const lang = info === '' ? '' : info.split(/\s+/)[0].toLowerCase();
+ const content = match[2];
+ const executable = EXECUTABLE_FENCE_LANGS.has(lang)
+ || (lang === '' && /^\s*#!/.test(content));
+ if (executable) {
+ fences.push({
+ lang: lang || 'shebang',
+ content,
+ start: match.index,
+ });
+ }
+ match = fenceRe.exec(body);
+ }
+ return fences;
+ }
+
+ function precedingAllowsToken(body, fenceStart) {
+ const prefix = body.slice(0, fenceStart).replace(/\s+$/, '');
+ const lines = prefix.split(/\r?\n/);
+ const window = lines.slice(-3).join('\n');
+ return /anti-pattern/i.test(window) || /do not/i.test(window);
+ }
+
-function isPortableBareDollarOne(fenceContent, index) {
- const before = fenceContent.slice(0, index);
- const after = fenceContent.slice(index + 2);
- // Perl/awk numeric compare: `$1 < 80`, `$1>=0`.
- if (/^\s*[<>=]/.test(after)) return true;
- // POSIX assignment of a function positional: `VAR=$1` or `VAR="$1"`.
- if (/=\s*["']?$/.test(before)) return true;
- return false;
-}
-
+ function findSubstitutionTokens(fenceContent) {
- const found = [];
- for (const pattern of CLAUDE_SUBSTITUTION_PATTERNS) {
++ return CLAUDE_SUBSTITUTION_PATTERNS.filter(pattern => {
+ pattern.regex.lastIndex = 0;
- let match = pattern.regex.exec(fenceContent);
- while (match !== null) {
- const skipBarePositional = pattern.token === '$1'
- && match[0] === '$1'
- && isPortableBareDollarOne(fenceContent, match.index);
- if (!skipBarePositional) {
- found.push(pattern.token);
- break;
- }
- match = pattern.regex.exec(fenceContent);
++ return pattern.regex.test(fenceContent);
++ }).map(pattern => pattern.token);
++}
++
++function inspectProjectionSubstitutions(skillName, content, treeLabel, findings) {
++ const { body } = stripFrontmatter(content);
++ for (const fence of findExecutableFences(body)) {
++ if (precedingAllowsToken(body, fence.start)) continue;
++ for (const token of findSubstitutionTokens(fence.content)) {
++ pushFinding(findings, { severity: 'error', code: 'substitution', skill: skillName,
++ token, message: `${treeLabel}/${substitutionMessage(skillName, fence.lang, token)}` });
+ }
+ }
- return found;
+ }
+
+ function countLines(content) {
+ if (content.length === 0) return 0;
+ return content.replace(/^\uFEFF/, '').split(/\r?\n/).length;
+ }
+
+ function relSkillMd(skillName) {
+ return `${skillName}/SKILL.md`;
+ }
+
+ function pushFinding(findings, finding) {
+ findings.push(finding);
+ }
+
+ function substitutionMessage(skillName, fenceLang, token) {
+ const base = `${relSkillMd(skillName)} - ${fenceLang} fence contains Claude-only substitution ${token}`;
+ if (token === '${CLAUDE_PROJECT_DIR}' || token === '$CLAUDE_PROJECT_DIR') {
+ return `${base}; rewrite to $(pwd) or an explicit path`;
+ }
+ return base;
+ }
+
+ function inspectCanonicalSkill(skillName, content, findings) {
+ const { frontmatter, body } = stripFrontmatter(content);
+ const values = frontmatter.present ? inspectFrontmatter(frontmatter.lines).values : {};
+ const declaredName = unquoteYamlScalar(values.name || '');
+ const lineCount = countLines(content);
+
+ if (declaredName && declaredName !== skillName) {
+ pushFinding(findings, {
+ severity: 'warn',
+ code: 'name-mismatch',
+ skill: skillName,
+ message: `${relSkillMd(skillName)} - frontmatter name '${declaredName}' does not match directory '${skillName}'`,
+ });
+ }
+
+ if (!/^##\s+When to Activate\b/m.test(body)) {
+ pushFinding(findings, {
+ severity: 'warn',
+ code: 'missing-when-to-activate',
+ skill: skillName,
+ message: `${relSkillMd(skillName)} - missing '## When to Activate' section`,
+ });
+ }
+
+ if (!/^##\s+Anti-Patterns\b/m.test(body)) {
+ pushFinding(findings, {
+ severity: 'warn',
+ code: 'missing-anti-patterns',
+ skill: skillName,
+ message: `${relSkillMd(skillName)} - missing '## Anti-Patterns' section`,
+ });
+ }
+
+ if (lineCount > 800) {
+ pushFinding(findings, {
+ severity: 'warn',
+ code: 'line-cap-800',
+ skill: skillName,
+ message: `${relSkillMd(skillName)} - body is ${lineCount} lines (CONTRIBUTING max 800)`,
+ });
+ } else if (lineCount > 500) {
+ pushFinding(findings, {
+ severity: 'warn',
+ code: 'line-cap-500',
+ skill: skillName,
+ message: `${relSkillMd(skillName)} - body is ${lineCount} lines (CONTRIBUTING target 500)`,
+ });
+ }
+
- for (const fence of findExecutableFences(body)) {
- if (precedingAllowsToken(body, fence.start)) continue;
- const tokens = findSubstitutionTokens(fence.content);
- for (const token of tokens) {
- pushFinding(findings, {
- severity: 'error',
- code: 'substitution',
- skill: skillName,
- token,
- message: substitutionMessage(skillName, fence.lang, token),
- });
- }
- }
++
+ }
+
+ function inspectCopyName(skillName, content, treeLabel, findings) {
+ const { frontmatter } = stripFrontmatter(content);
+ if (!frontmatter.present) return;
+ const declaredName = unquoteYamlScalar(inspectFrontmatter(frontmatter.lines).values.name || '');
+ if (declaredName && declaredName !== skillName) {
+ pushFinding(findings, {
+ severity: 'error',
+ code: 'copy-name-mismatch',
+ skill: skillName,
+ message: `${treeLabel}/${relSkillMd(skillName)} - frontmatter name '${declaredName}' does not match directory '${skillName}'`,
+ });
+ }
+ }
+
+ function inspectCodexCopy(skillName, content, findings) {
+ const { frontmatter } = stripFrontmatter(content);
+ inspectCopyName(skillName, content, '.agents/skills', findings);
++ inspectProjectionSubstitutions(skillName, content, '.agents/skills', findings);
+ if (!frontmatter.present) return;
+
+ const keys = Object.keys(inspectFrontmatter(frontmatter.lines).values);
+ const unexpected = keys.filter(key => !ALLOWED_CODEX_FRONTMATTER_KEYS.has(key));
+ if (unexpected.length > 0) {
+ pushFinding(findings, {
+ severity: 'error',
+ code: 'codex-key',
+ skill: skillName,
+ message: `.agents/skills/${relSkillMd(skillName)} - Codex-forbidden frontmatter key${unexpected.length === 1 ? '' : 's'}: ${unexpected.join(', ')}`,
+ });
+ }
+ }
+
+ function validateSkillHostCompat(options = {}) {
+ const root = options.root || DEFAULT_ROOT;
+ const inventory = Boolean(options.inventory);
+ const strictChecklist = Boolean(options.strictChecklist);
+ const skillsDir = path.join(root, 'skills');
+ const codexDir = path.join(root, '.agents', 'skills');
+ const cursorDir = path.join(root, '.cursor', 'skills');
+ const findings = [];
+
+ if (!fs.existsSync(skillsDir)) {
+ return {
+ ok: true,
+ skipped: true,
+ message: 'No curated skills directory (skills/), skipping',
+ findings: [],
+ counts: emptyCounts(),
+ };
+ }
+
+ const canonicalSkills = listSkillDirs(skillsDir);
+ const codexSkills = listSkillDirs(codexDir);
+ const cursorSkills = listSkillDirs(cursorDir);
+ const openaiListed = listOpenaiYamlSkills(root);
+ const skillsWithCanonical = new Set(canonicalSkills);
+
+ for (const skillName of canonicalSkills) {
+ const skillMd = path.join(skillsDir, skillName, 'SKILL.md');
+ const content = readFileIfPresent(skillMd);
+ if (content === null) continue;
+ inspectCanonicalSkill(skillName, content, findings);
+ }
+
+ for (const skillName of openaiListed) {
+ if (!skillsWithCanonical.has(skillName)) continue;
+ const copyMd = path.join(codexDir, skillName, 'SKILL.md');
+ if (!fs.existsSync(copyMd)) {
+ pushFinding(findings, {
+ severity: 'error',
+ code: 'missing-codex-copy',
+ skill: skillName,
+ message: `agents/openai.yaml lists '${skillName}' but .agents/skills/${skillName}/ is missing`,
+ });
+ }
+ }
+
+ for (const skillName of codexSkills) {
+ const copyMd = path.join(codexDir, skillName, 'SKILL.md');
+ const content = readFileIfPresent(copyMd);
+ if (content === null) continue;
+ inspectCodexCopy(skillName, content, findings);
+ }
+
+ for (const skillName of cursorSkills) {
+ const copyMd = path.join(cursorDir, skillName, 'SKILL.md');
+ const content = readFileIfPresent(copyMd);
+ if (content === null) continue;
+ inspectCopyName(skillName, content, '.cursor/skills', findings);
++ inspectProjectionSubstitutions(skillName, content, '.cursor/skills', findings);
+ }
+
+ const resolved = findings.map(finding => {
+ if (strictChecklist && CHECKLIST_CODES.has(finding.code) && finding.severity === 'warn') {
+ return { ...finding, severity: 'error' };
+ }
+ return finding;
+ });
+
+ const counts = summarizeCounts(canonicalSkills.length, resolved);
+ const errorCount = resolved.filter(finding => finding.severity === 'error').length;
+
+ return {
+ ok: inventory || errorCount === 0,
+ skipped: false,
+ inventory,
+ findings: resolved,
+ counts,
+ message: inventory
+ ? JSON.stringify(counts)
+ : formatSummary(canonicalSkills.length, counts),
+ };
+ }
+
+ function emptyCounts() {
+ return {
+ skillsScanned: 0,
+ errors: 0,
+ warnings: 0,
+ substitutions: 0,
+ codexKeys: 0,
+ missingCodexCopies: 0,
+ copyNameMismatches: 0,
+ checklistWarnings: 0,
+ };
+ }
+
+ function summarizeCounts(skillsScanned, findings) {
+ const counts = emptyCounts();
+ counts.skillsScanned = skillsScanned;
+ for (const finding of findings) {
+ if (finding.severity === 'error') counts.errors += 1;
+ if (finding.severity === 'warn') counts.warnings += 1;
+ if (finding.code === 'substitution') counts.substitutions += 1;
+ if (finding.code === 'codex-key') counts.codexKeys += 1;
+ if (finding.code === 'missing-codex-copy') counts.missingCodexCopies += 1;
+ if (finding.code === 'copy-name-mismatch') counts.copyNameMismatches += 1;
+ if (CHECKLIST_CODES.has(finding.code)) counts.checklistWarnings += 1;
+ }
+ return counts;
+ }
+
+ function formatSummary(skillCount, counts) {
+ let msg = `Validated host compatibility for ${skillCount} skill directories`;
+ const extras = [];
+ if (counts.errors > 0) extras.push(`${counts.errors} error${counts.errors === 1 ? '' : 's'}`);
+ if (counts.warnings > 0) extras.push(`${counts.warnings} warning${counts.warnings === 1 ? '' : 's'}`);
+ if (extras.length > 0) msg += ` (${extras.join(', ')})`;
+ return msg;
+ }
+
+ function reportFindings(result, stdout, stderr) {
+ if (result.skipped) {
+ stdout.write(`${result.message}\n`);
+ return;
+ }
+
+ if (result.inventory) {
+ stdout.write(`${result.message}\n`);
+ return;
+ }
+
+ for (const finding of result.findings) {
+ const line = `${finding.severity === 'error' ? 'ERROR' : 'WARN'}: ${finding.message}\n`;
+ if (finding.severity === 'error') stderr.write(line);
+ else stderr.write(line);
+ }
+ stdout.write(`${result.message}\n`);
+ }
+
+ function run(argv = process.argv.slice(2), options = {}) {
+ const stdout = options.stdout || process.stdout;
+ const stderr = options.stderr || process.stderr;
+
+ try {
+ const args = parseArgs(argv);
+ const result = validateSkillHostCompat({
+ root: options.root || args.root,
+ inventory: args.inventory,
+ strictChecklist: args.strictChecklist,
+ });
+ reportFindings(result, stdout, stderr);
+ return result.ok ? 0 : 1;
+ } catch (error) {
+ stderr.write(`ERROR: ${error.message}\n`);
+ return 1;
+ }
+ }
+
+ if (require.main === module) {
+ process.exit(run());
+ }
+
+ module.exports = {
+ ALLOWED_CODEX_FRONTMATTER_KEYS,
+ CLAUDE_SUBSTITUTION_PATTERNS,
+ extractTopLevelList,
+ findExecutableFences,
+ parseArgs,
+ run,
+ validateSkillHostCompat,
+ };
diff --cc skills/skill-host-compat/SKILL.md
index 000000000,6afc6aa78..220e8b311
mode 000000,100644..100644
--- a/skills/skill-host-compat/SKILL.md
+++ b/skills/skill-host-compat/SKILL.md
@@@ -1,0 -1,103 +1,102 @@@
+ ---
+ name: skill-host-compat
+ description: Lint ECC skills for Codex/Cursor-safe frontmatter and Claude-only substitutions before a skill PR.
+ origin: ECC
+ ---
+
+ # 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
- (`${CLAUDE_SESSION_ID}`, `${CLAUDE_SKILL_DIR}`, `${CLAUDE_PLUGIN_ROOT}`,
++ 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
+
-Do not put Claude-only substitutions in bash blocks. This fence is the
++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. Mention other Claude env vars in prose, not in executable
- fences.
++ 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
diff --cc tests/ci/validate-skill-host-compat.test.js
index 000000000,88ba8c01d..09ba27706
mode 000000,100644..100644
--- a/tests/ci/validate-skill-host-compat.test.js
+++ b/tests/ci/validate-skill-host-compat.test.js
@@@ -1,0 -1,627 +1,664 @@@
+ #!/usr/bin/env node
+ /**
+ * Fixture tests for scripts/ci/validate-skill-host-compat.js.
+ *
+ * Uses tmp dirs, not the live catalog.
+ */
+
+ 'use strict';
+
+ const assert = require('assert');
+ const fs = require('fs');
+ const os = require('os');
+ const path = require('path');
+ const { spawnSync } = require('child_process');
+
+ const repoRoot = path.join(__dirname, '..', '..');
+ const validatorPath = path.join(repoRoot, 'scripts', 'ci', 'validate-skill-host-compat.js');
+
+ function test(name, fn) {
+ try {
+ fn();
+ console.log(` ✓ ${name}`);
+ return true;
+ } catch (error) {
+ console.log(` ✗ ${name}`);
+ console.log(` Error: ${error.message}`);
+ return false;
+ }
+ }
+
+ function createRoot() {
+ return fs.mkdtempSync(path.join(os.tmpdir(), 'skill-host-compat-'));
+ }
+
+ function cleanup(dir) {
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+
+ function writeSkill(root, skillName, body, options = {}) {
+ const tree = options.tree || 'skills';
+ const extraFrontmatter = options.frontmatter || {};
+ const dir = path.join(root, tree, skillName);
+ fs.mkdirSync(dir, { recursive: true });
+ const lines = ['---', `name: ${options.name || skillName}`];
+ if (options.description !== false) {
+ lines.push(`description: ${options.description || `Fixture skill ${skillName}`}`);
+ }
+ for (const [key, value] of Object.entries(extraFrontmatter)) {
+ lines.push(`${key}: ${value}`);
+ }
+ lines.push('---', '');
+ lines.push(body);
+ fs.writeFileSync(path.join(dir, 'SKILL.md'), `${lines.join('\n')}\n`);
+ }
+
+ function writeOpenaiYaml(root, skillNames) {
+ const dir = path.join(root, 'agents');
+ fs.mkdirSync(dir, { recursive: true });
+ const body = ['skills:', ...skillNames.map(name => ` - ${name}`)].join('\n');
+ fs.writeFileSync(path.join(dir, 'openai.yaml'), `${body}\n`);
+ }
+
+ function runValidator(root, extraArgs = []) {
+ return spawnSync('node', [validatorPath, '--root', root, ...extraArgs], {
+ encoding: 'utf8',
+ cwd: repoRoot,
+ timeout: 10000,
+ });
+ }
+
+ function checklistBody(title) {
+ return [
+ `# ${title}`,
+ '',
+ '## When to Activate',
+ '',
+ '- Writing or reviewing a skill PR',
+ '',
+ '## Anti-Patterns',
+ '',
+ '- Shipping a Codex copy with extra frontmatter keys',
+ '',
+ ].join('\n');
+ }
+
+ console.log('\n=== Testing validate-skill-host-compat.js ===\n');
+
+ let passed = 0;
+ let failed = 0;
+
+ function check(name, fn) {
+ if (test(name, fn)) passed += 1;
+ else failed += 1;
+ }
+
+ check('exports extractFrontmatter and inspectFrontmatter without running the CLI', () => {
+ const skills = require('../../scripts/ci/validate-skills');
+ assert.strictEqual(typeof skills.extractFrontmatter, 'function');
+ assert.strictEqual(typeof skills.inspectFrontmatter, 'function');
+ const fm = skills.extractFrontmatter('---\nname: demo\ndescription: hi\n---\n# Demo\n');
+ assert.strictEqual(fm.present, true);
+ const inspected = skills.inspectFrontmatter(fm.lines);
+ assert.strictEqual(inspected.values.name, 'demo');
+ });
+
+ check('happy: skill with name/description only, no Codex copy required, exits 0', () => {
+ const root = createRoot();
+ try {
+ writeSkill(root, 'portable', checklistBody('Portable'));
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+ assert.ok(result.stdout.includes('Validated host compatibility for 1'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('happy: Codex copy whose frontmatter is the allowlist only, exits 0', () => {
+ const root = createRoot();
+ try {
+ writeSkill(root, 'portable', checklistBody('Portable'), {
+ frontmatter: { origin: 'ECC' },
+ });
+ writeSkill(root, 'portable', checklistBody('Portable'), {
+ tree: '.agents/skills',
+ });
+ writeOpenaiYaml(root, ['portable']);
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('fail: bash fence contains ${CLAUDE_SESSION_ID}', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'leaky',
+ `${checklistBody('Leaky')}\n## Code Examples\n\n\`\`\`bash\necho "\${CLAUDE_SESSION_ID}"\n\`\`\`\n`
+ );
++ writeSkill(root, 'leaky', fs.readFileSync(path.join(root, 'skills', 'leaky', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 1);
+ assert.ok(result.stderr.includes('ERROR:'));
+ assert.ok(result.stderr.includes('leaky'));
+ assert.ok(result.stderr.includes('${CLAUDE_SESSION_ID}'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('fail: bash fence contains ${CLAUDE_PROJECT_DIR}', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'proj',
+ `${checklistBody('Proj')}\n## Code Examples\n\n\`\`\`bash\ncd "\${CLAUDE_PROJECT_DIR}"\n\`\`\`\n`
+ );
++ writeSkill(root, 'proj', fs.readFileSync(path.join(root, 'skills', 'proj', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 1);
+ assert.ok(result.stderr.includes('ERROR:'));
+ assert.ok(result.stderr.includes('proj'));
+ assert.ok(result.stderr.includes('${CLAUDE_PROJECT_DIR}'));
+ assert.ok(result.stderr.includes('rewrite to $(pwd) or an explicit path'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('fail: $CLAUDE_PROJECT_DIR used as a substitution in a bash fence', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'proj',
+ `${checklistBody('Proj')}\n## Code Examples\n\n\`\`\`sh\ncd "$CLAUDE_PROJECT_DIR"\n\`\`\`\n`
+ );
++ writeSkill(root, 'proj', fs.readFileSync(path.join(root, 'skills', 'proj', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 1);
+ assert.ok(result.stderr.includes('$CLAUDE_PROJECT_DIR'));
+ assert.ok(result.stderr.includes('rewrite to $(pwd) or an explicit path'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('bash fence $(pwd) is accepted in place of CLAUDE_PROJECT_DIR', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'proj',
+ `${checklistBody('Proj')}\n## Code Examples\n\n\`\`\`bash\ncd "$(pwd)"\n\`\`\`\n`
+ );
++ writeSkill(root, 'proj', fs.readFileSync(path.join(root, 'skills', 'proj', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0, result.stderr);
+ assert.ok(!result.stderr.includes('ERROR:'));
+ assert.ok(!result.stderr.includes('CLAUDE_PROJECT_DIR'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('bash fence variables that only contain CLAUDE_PROJECT_DIR are accepted', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'proj',
+ `${checklistBody('Proj')}\n## Code Examples\n\n\`\`\`bash\ncd "$MY_CLAUDE_PROJECT_DIR"\ncd "\${MY_CLAUDE_PROJECT_DIR}"\nls "$CLAUDE_PROJECT_DIR_TMP"\nls "\${CLAUDE_PROJECT_DIR_TMP}"\n\`\`\`\n`
+ );
++ writeSkill(root, 'proj', fs.readFileSync(path.join(root, 'skills', 'proj', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0, result.stderr);
+ assert.ok(!result.stderr.includes('ERROR:'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('prose mention of CLAUDE_PROJECT_DIR does not fail', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'prose',
+ `${checklistBody('Prose')}\nThe project root is \`CLAUDE_PROJECT_DIR\`, then cwd.\n`
+ );
++ writeSkill(root, 'prose', fs.readFileSync(path.join(root, 'skills', 'prose', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0, result.stderr);
+ assert.ok(!result.stderr.includes('ERROR:'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('fail: $ARGUMENTS used as a substitution in a bash fence', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'args',
+ `${checklistBody('Args')}\n## Code Examples\n\n\`\`\`bash\necho "$ARGUMENTS"\n\`\`\`\n`
+ );
++ writeSkill(root, 'args', fs.readFileSync(path.join(root, 'skills', 'args', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 1);
+ assert.ok(result.stderr.includes('args'));
+ assert.ok(result.stderr.includes('$ARGUMENTS'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('fail: .agents/skills/foo/SKILL.md has version:', () => {
+ const root = createRoot();
+ try {
+ writeSkill(root, 'foo', checklistBody('Foo'));
+ writeSkill(root, 'foo', checklistBody('Foo'), {
+ tree: '.agents/skills',
+ frontmatter: { version: '1.0.0' },
+ });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 1);
+ assert.ok(result.stderr.includes('version'));
+ assert.ok(result.stderr.includes('.agents/skills/foo/SKILL.md'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('fail: agents/openai.yaml lists foo but .agents/skills/foo/ is missing', () => {
+ const root = createRoot();
+ try {
+ writeSkill(root, 'foo', checklistBody('Foo'));
+ writeOpenaiYaml(root, ['foo']);
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 1);
+ assert.ok(result.stderr.includes('agents/openai.yaml lists \'foo\''));
+ assert.ok(result.stderr.includes('.agents/skills/foo/'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('warn-only: missing ## When to Activate exits 0 unless --strict-checklist', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'thin',
+ '# Thin\n\n## Anti-Patterns\n\n- Missing activation heading\n'
+ );
+ const warnResult = runValidator(root);
+ assert.strictEqual(warnResult.status, 0, warnResult.stderr);
+ assert.ok(warnResult.stderr.includes('WARN:'));
+ assert.ok(warnResult.stderr.includes('When to Activate'));
+
+ const strictResult = runValidator(root, ['--strict-checklist']);
+ assert.strictEqual(strictResult.status, 1);
+ assert.ok(strictResult.stderr.includes('ERROR:'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('anti-pattern fence still matches when the do-not line wraps', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'wrapped',
+ [
+ '# Wrapped',
+ '',
+ '## When to Activate',
+ '',
+ '- Reviewing a skill PR',
+ '',
+ '## Anti-Patterns',
+ '',
+ 'Do not put Claude-only substitutions in bash blocks. This fence is the',
+ 'forbidden pattern:',
+ '',
+ '```bash',
+ 'echo "${CLAUDE_SESSION_ID}"',
+ '```',
+ '',
+ ].join('\n')
+ );
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0, result.stderr);
+ assert.ok(!result.stderr.includes('ERROR:'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('anti-pattern fence that quotes the token as forbidden exits 0', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'quoted',
+ [
+ '# Quoted',
+ '',
+ '## When to Activate',
+ '',
+ '- Reviewing a skill PR',
+ '',
+ '## Anti-Patterns',
+ '',
+ 'Do not put Claude-only substitutions in bash blocks:',
+ '',
+ '```bash',
+ 'echo "${CLAUDE_SESSION_ID}"',
+ '```',
+ '',
+ ].join('\n')
+ );
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0, result.stderr);
+ assert.ok(!result.stderr.includes('ERROR:'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('empty skills/ tmp root exits 0', () => {
+ const root = createRoot();
+ try {
+ fs.mkdirSync(path.join(root, 'skills'));
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0, result.stderr);
+ assert.ok(result.stdout.includes('Validated host compatibility for 0'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('missing skills directory skips with exit 0', () => {
+ const root = createRoot();
+ try {
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0, result.stderr);
+ assert.ok(result.stdout.includes('skipping'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('origin on canonical copy is allowed; origin on Codex copy fails', () => {
+ const root = createRoot();
+ try {
+ writeSkill(root, 'foo', checklistBody('Foo'), { frontmatter: { origin: 'ECC' } });
+ writeSkill(root, 'foo', checklistBody('Foo'), {
+ tree: '.agents/skills',
+ frontmatter: { origin: 'ECC' },
+ });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 1);
+ assert.ok(result.stderr.includes('origin'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('Cursor copy name mismatch is an error; extra Cursor copies are not required', () => {
+ const root = createRoot();
+ try {
+ writeSkill(root, 'alpha', checklistBody('Alpha'));
+ writeSkill(root, 'alpha', checklistBody('Alpha'), {
+ tree: '.cursor/skills',
+ name: 'beta',
+ });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 1);
+ assert.ok(result.stderr.includes('.cursor/skills/alpha/SKILL.md'));
+ assert.ok(result.stderr.includes('does not match directory'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('--inventory prints JSON counts and exits 0 even with errors', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'leaky',
+ `${checklistBody('Leaky')}\n## Code Examples\n\n\`\`\`bash\necho "$CLAUDE_SKILL_DIR"\n\`\`\`\n`
+ );
++ writeSkill(root, 'leaky', fs.readFileSync(path.join(root, 'skills', 'leaky', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root, ['--inventory']);
+ assert.strictEqual(result.status, 0, result.stderr);
+ const counts = JSON.parse(result.stdout.trim());
+ assert.strictEqual(counts.skillsScanned, 1);
+ assert.ok(counts.substitutions >= 1);
+ assert.ok(counts.errors >= 1);
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('empty-language shebang fence is scanned; markdown fence is not', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'mixed',
+ [
+ '# Mixed',
+ '',
+ '## When to Activate',
+ '',
+ '- Reviewing fences',
+ '',
+ '## Anti-Patterns',
+ '',
+ '- Putting substitutions in bash',
+ '',
+ '```markdown',
+ 'Parse $ARGUMENTS in a command file, not in a skill bash block.',
+ '```',
+ '',
+ '```',
+ '#!/bin/sh',
+ 'echo "$CLAUDE_PLUGIN_ROOT"',
+ '```',
+ '',
+ ].join('\n')
+ );
++ writeSkill(root, 'mixed', fs.readFileSync(path.join(root, 'skills', 'mixed', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 1);
+ assert.ok(result.stderr.includes('$CLAUDE_PLUGIN_ROOT'));
+ assert.ok(!result.stderr.includes('$ARGUMENTS'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('Codex copy name mismatch is an error', () => {
+ const root = createRoot();
+ try {
+ writeSkill(root, 'foo', checklistBody('Foo'));
+ writeSkill(root, 'foo', checklistBody('Foo'), {
+ tree: '.agents/skills',
+ name: 'bar',
+ });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 1);
+ assert.ok(result.stderr.includes('.agents/skills/foo/SKILL.md'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('--root without a path exits 1', () => {
+ const result = spawnSync('node', [validatorPath, '--root'], {
+ encoding: 'utf8',
+ cwd: repoRoot,
+ timeout: 10000,
+ });
+ assert.strictEqual(result.status, 1);
+ assert.ok(result.stderr.includes('--root requires a directory path'));
+ });
+
+ check('canonical name mismatch warns and does not fail', () => {
+ const root = createRoot();
+ try {
+ writeSkill(root, 'foo', checklistBody('Foo'), { name: 'bar' });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0, result.stderr);
+ assert.ok(result.stderr.includes('WARN:'));
+ assert.ok(result.stderr.includes('does not match directory'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('missing Anti-Patterns heading warns', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'thin',
+ '# Thin\n\n## When to Activate\n\n- Reviewing a skill\n'
+ );
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0);
+ assert.ok(result.stderr.includes('Anti-Patterns'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('body over 500 lines warns; over 800 stays warn unless --strict-checklist', () => {
+ const root = createRoot();
+ try {
+ const overFive = `${checklistBody('Long')}\n${'line\n'.repeat(500)}`;
+ writeSkill(root, 'longish', overFive);
+ const warnResult = runValidator(root);
+ assert.strictEqual(warnResult.status, 0, warnResult.stderr);
+ assert.ok(warnResult.stderr.includes('500'));
+
+ cleanup(root);
+ const root2 = createRoot();
+ const overEight = `${checklistBody('Huge')}\n${'line\n'.repeat(800)}`;
+ writeSkill(root2, 'huge', overEight);
+ const hugeWarn = runValidator(root2);
+ assert.strictEqual(hugeWarn.status, 0, hugeWarn.stderr);
+ assert.ok(hugeWarn.stderr.includes('800'));
+ const hugeStrict = runValidator(root2, ['--strict-checklist']);
+ assert.strictEqual(hugeStrict.status, 1);
+ cleanup(root2);
+ } finally {
+ if (fs.existsSync(root)) cleanup(root);
+ }
+ });
+
-check('bash fence ${1} is treated as a Claude substitution', () => {
++check('bash fence ${1} is accepted as an ambiguous POSIX parameter', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'pos',
+ `${checklistBody('Pos')}\n## Code Examples\n\n\`\`\`bash\necho "\${1}"\n\`\`\`\n`
+ );
++ writeSkill(root, 'pos', fs.readFileSync(path.join(root, 'skills', 'pos', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root);
- assert.strictEqual(result.status, 1);
- assert.ok(result.stderr.includes('$1'));
++ assert.strictEqual(result.status, 0, result.stderr);
++ assert.ok(!result.stderr.includes('ERROR:'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('POSIX VAR=$1 assignment is not a Claude substitution', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'posix',
+ `${checklistBody('Posix')}\n## Code Examples\n\n\`\`\`bash\nmove_dir() {\n SOURCE=$1\n DEST=$2\n}\n\`\`\`\n`
+ );
++ writeSkill(root, 'posix', fs.readFileSync(path.join(root, 'skills', 'posix', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0, result.stderr);
+ assert.ok(!result.stderr.includes('ERROR:'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
+ check('Perl/awk $1 numeric compare is not a Claude substitution', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'cover',
+ `${checklistBody('Cover')}\n## Code Examples\n\n\`\`\`bash\nperl -ne 'if (/Total.*?(\\d+)/) { exit 1 if $1 < 80 }'\n\`\`\`\n`
+ );
++ writeSkill(root, 'cover', fs.readFileSync(path.join(root, 'skills', 'cover', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root);
+ assert.strictEqual(result.status, 0, result.stderr);
+ assert.ok(!result.stderr.includes('ERROR:'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
-check('echo $1 in a bash fence is treated as a Claude substitution', () => {
++check('echo $1 in a bash fence is accepted as an ambiguous POSIX parameter', () => {
+ const root = createRoot();
+ try {
+ writeSkill(
+ root,
+ 'echoone',
+ `${checklistBody('Echo')}\n## Code Examples\n\n\`\`\`bash\necho $1\n\`\`\`\n`
+ );
++ writeSkill(root, 'echoone', fs.readFileSync(path.join(root, 'skills', 'echoone', 'SKILL.md'), 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''), { tree: '.agents/skills' });
+ const result = runValidator(root);
- assert.strictEqual(result.status, 1);
- assert.ok(result.stderr.includes('$1'));
++ assert.strictEqual(result.status, 0, result.stderr);
++ assert.ok(!result.stderr.includes('ERROR:'));
+ } finally {
+ cleanup(root);
+ }
+ });
+
++check('canonical Claude examples remain available while unresolved Codex projections fail', () => {
++ const root = createRoot();
++ try {
++ const body = `${checklistBody('Scoped')}\n## Workflow\n\n\`\`\`bash\necho "$CLAUDE_SKILL_DIR"\n\`\`\`\n`;
++ writeSkill(root, 'scoped', body);
++ assert.strictEqual(runValidator(root).status, 0);
++ writeSkill(root, 'scoped', body, { tree: '.agents/skills' });
++ const result = runValidator(root);
++ assert.strictEqual(result.status, 1);
++ assert.ok(result.stderr.includes('.agents/skills/scoped/SKILL.md'));
++ } finally { cleanup(root); }
++});
++
++check('POSIX function arguments $1 and ${1} pass in the Codex projection', () => {
++ const root = createRoot();
++ try {
++ const body = `${checklistBody('Positional')}\n## Workflow\n\n\`\`\`sh\nprint_arg() { printf '%s\\n' "$1" "\${1}"; }\nprint_arg hello\n\`\`\`\n`;
++ writeSkill(root, 'positional', body);
++ writeSkill(root, 'positional', body, { tree: '.agents/skills' });
++ const result = runValidator(root);
++ assert.strictEqual(result.status, 0, result.stderr);
++ } finally { cleanup(root); }
++});
++
+ console.log(`\nPassed: ${passed}`);
+ console.log(`Failed: ${failed}`);
+ process.exit(failed > 0 ? 1 : 0);
diff --cc tests/scripts/npm-publish-surface.test.js
index ce9afaae8,885be5893..5a810ef04
--- a/tests/scripts/npm-publish-surface.test.js
+++ b/tests/scripts/npm-publish-surface.test.js
@@@ -303,12 -302,8 +307,13 @@@ function main()
"schemas/memory.schema.json",
"skills/backend-patterns/SKILL.md",
"skills/skill-comply/SKILL.md",
+ "skills/skill-host-compat/SKILL.md",
"skills/unified-memory/SKILL.md",
+ "scripts/agent-convert.js",
+ "scripts/lib/agent-ir.js",
+ "scripts/lib/agent-tool-map.js",
+ "scripts/lib/agent-emit-pi.js",
+ "schemas/agent.schema.json",
]) {
assert.ok(
packagedPaths.has(requiredPath),