skill-validator-omni

Validates skills against seven authoring standards across all agents. Use to audit/certify.

Skill Validator

The compliance gate for agent skills: validates a skill, a plugin, or a whole repo against seven standards in one command. Flagship: Agent Plugins 1.0.0 (agent-plugins.org) — the open, vendor-neutral spec for packaging Agent Skills and MCP servers into portable plugins, published by a TSC of Core Maintainers from Amazon, Cursor, Microsoft, OpenAI, and Vercel. Also enforces the agentskills.io spec, Anthropic best practices, Hermes in-repo standard, OpenAgent skills.sh discoverability, Claude Code marketplace installability, and the OpenAI Codex skill format. Ships as npx skill-validator-omni (Node, zero Python deps) and as scripts/validate.js for local use.

This is a validation/audit tool. Creation/scaffolding is a secondary workflow — the differentiator is certifying that a skill will install and work across agents, not generating SKILL.md files.

When to Use

• User asks to "validate", "audit", "check", "lint", or "certify" a skill
• User wants to know if a skill/repo is installable via npx skills add or Claude Code
• Before publishing a skill repo to skills.sh or a Claude marketplace
• As a CI gate on a skills repo (exit codes: 0 pass, 1 failed checks, 2 usage error)
• Creating a new skill that must be standards-compliant from day one (scaffold, then validate)

Don't Use For

• Subjective quality review / multi-agent QA — use skill-engineer (quality gates, Designer/Reviewer/Tester)
• Skill authoring inside the hermes-agent repo itself — use hermes-agent-skill-authoring (repo tests + docs regen)
• Pure creation with no standards concern — skill-creator (anthropics/skills) does that

Prerequisites

• Node.js >= 18 (runs scripts/validate.js or the npm CLI)
• Published CLI: npx skill-validator-omni <dir> [--json] (fetched from npm; needs only Node)
• Local script: node scripts/validate.js <dir> (needs the yaml package — the repo's npm install covers it)

What Gets Validated

Standard	Checks
Agent Plugins 1.0.0	plugin.json manifest: canonical $schema (agent-plugins.org/schemas/1.0.0/plugin.schema.json), name format (1-64, lowercase alnum/hyphen/dot, no --/..), closed field set (unknown fields flagged), keywords/author typing, skills/ layout (immediate children), optional mcp.json parses
agentskills.io spec	name == dir, name format ([a-z0-9]+(-[a-z0-9]+)*, <=64, no --), description 1-1024, compatibility <=500, allowed-tools typing, body non-empty
Anthropic best practices	third-person description, body < 500 lines, progressive disclosure (supporting dirs required above 200 lines)
Hermes in-repo	description <=60 + ends with ., version/author/license/platforms, metadata.hermes.{tags, related_skills}, required sections
OpenAgent skills.sh	discoverable layout (root SKILL.md, skills/ up to 3 levels, agent dirs), every dir name == frontmatter name, well-known index $schema
Claude Code	marketplace.json (JSON + name + plugins), plugin.json + <plugin>/skills/ per plugin, .claude/skills/ project layout
OpenAI Codex	frontmatter limited to name/description/license/allowed-tools/metadata (mirrors openai/skills quick_validate.py), hyphen-case name == dir (<=64, no edge/consecutive hyphens), name/desc present, description no angle brackets <=1024 + trigger words (docs guidance), body < 500 lines, no ancillary docs (README/INSTALLATION_GUIDE/QUICK_REFERENCE/CHANGELOG), agents/openai.yaml keys (interface/policy/dependencies), repo .agents/skills/.codex/skills/plugin.json layout

Every skill discovered in a repo (nested skills/<category>/<skill>/) gets the full suite — a broken skill can't hide inside a big repo.

Installability (what "installable" means)

A skill project passes install checks when it satisfies at least one discoverable layout:

• Agent Plugins 1.0.0 — portable plugin package: plugin.json at the plugin root with $schema: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json; skills in skills/<name>/SKILL.md (immediate children, agentskills.io format); optional mcp.json for MCP servers. Loadable by compatible clients from Amazon, Cursor, Microsoft, OpenAI, and Vercel ecosystems.
• npx skills add <owner/repo> (skills.sh CLI) discovers from:
  • SKILL.md at repo root (single-skill repo)
  • skills/<name>/SKILL.md (container dirs walked up to 3 levels)
  • agent dirs: .claude/skills/, .agents/skills/, .cursor/skills/, .codex/skills/, .gemini/skills/, .config/opencode/skills/
  • HTTP publishers: .well-known/agent-skills/index.json with $schema: https://schemas.agentskills.io/discovery/0.2.0/schema.json (legacy: .well-known/skills/)
• Claude Code — plugin marketplace: .claude-plugin/marketplace.json (name + plugins) at root, added with /plugin marketplace add <owner>/<repo> (CLI claude plugin marketplace add github.com/<owner>/<repo>), then /plugin install <plugin>@<marketplace>; each plugin needs .claude-plugin/plugin.json (name) + <plugin>/skills/<name>/SKILL.md. Repos with only .claude/skills/<name>/SKILL.md auto-discover when Claude Code runs there.
• OpenAI Codex — Codex CLI auto-scans .agents/skills from the working directory up to the repo root (legacy: .codex/skills); distro beyond a local repo goes through Agent Plugins (plugin.json, covered above) or npx skills add <owner>/<repo> -a codex. Skill frontmatter must match openai/skills quick_validate.py: only name/description/license/allowed-tools/metadata allowed.

Procedure

1. Validate — npx skill-validator-omni <dir> (or node scripts/validate.js <dir>). Read the PASS/FAIL report. Add -s <standard> to run one standard (repeatable; --list-standards shows names; --all is the default).
2. Fix failures — each check prints the offending detail; fix frontmatter/structure and re-run until exit 0.
3. CI gate — npx skill-validator-omni <dir> --json | jq -e '.ok' (JSON report, exit 1 on failure).
4. Verify installability for publish — npx skills add <owner>/<repo> --list -y must list your skills; for Claude, confirm the marketplace/plugin layouts above.
5. Scaffold (secondary) — copy references/frontmatter-template.md into a new SKILL.md, fill fields, then validate from step 1.

Common Edge Cases

• Validating a repo vs a single skill — point at either; the tool discovers skills/, agent dirs, and plugin dirs automatically
• Skill with no metadata.hermes — Hermes checks fail; that's correct if you publish outside Hermes, but the repo-level skill still gets spec + Anthropic + OpenAgent checks
• yaml package missing — install deps: npm install in the skill-validator-omni repo, or use the published CLI which bundles it
• Windows — the npm CLI needs only Node (no python3 requirement)

Pitfalls

• Treating open-agent.io (the AFK-surf product site) as a standards source — it publishes NO skill spec. The real "open agent" standards are agent-plugins.org (Agent Plugins 1.0.0, vendor-neutral, Amazon/Cursor/Microsoft/OpenAI/Vercel) and skills.sh (schema at schemas.agentskills.io), both enforced by this validator
• Confusing the Agent Plugins manifest with a Claude plugin manifest — Agent Plugins uses root plugin.json + $schema: agent-plugins.org/schemas/1.0.0/plugin.schema.json (closed field set); Claude uses .claude-plugin/marketplace.json + .claude-plugin/plugin.json. Both get checked
• Claiming "installable" without the layout: npx skills add discovers root SKILL.md, skills/, or agent dirs — a skill buried in examples/ is NOT discoverable; a Claude marketplace needs .claude-plugin/marketplace.json, not just plugin code
• Letting the repo copy of scripts/validate.js drift from github.com/adelpro/skill-validator-omni/src/validate.js — sync after changing either side
• Adding the progressive-disclosure requirement to tiny skills — it only applies above 200 lines
• Expecting one SKILL.md to satisfy both Hermes and Codex frontmatter — Hermes requires version/author/platforms; Codex's closed field set (name/description/license/allowed-tools/metadata) rejects them. The standards conflict by design; the per-standard report shows which side a skill meets, so don't "fix" a Codex flag by deleting Hermes fields (and vice-versa)

Verification

• npx skill-validator-omni <dir> exits 0 with no failures on a compliant skill; report ends with per-standard scores ([PASS] Agent Plugins 1.0.0: 7/7 etc.)
• JSON mode carries a standards array (one object per standard: passed/failed/total/ok) for per-standard CI gating: jq -e '.standards["Agent Plugins 1.0.0"].ok'
• node scripts/validate.js <dir> on this skill directory passes all checks except the Codex frontmatter restriction — expected: this is a Hermes-flavoured skill, and Hermes requires version/author/platforms fields that Codex's closed field set rejects. The conflict is per-standard by design; run -s codex vs -s hermes to see each side
• Repo test suite green: node --test in ~/projects/skill-validator-omni (25 tests: spec, OpenAgent, well-known, Claude, Agent Plugins, Codex, fallback parser)
• Broken cases proven: name mismatch → exit 1, invalid marketplace.json → FAIL, missing well-known $schema → FAIL, Agent Plugins bad name/missing $schema/unknown field → FAIL, Codex unexpected frontmatter field/angle-bracket description/ancillary docs → FAIL
• scripts/validate.js matches github.com/adelpro/skill-validator-omni/src/validate.js