| name | skill-artifact |
| description | Validate, diagnose, and understand Agent Skills (SKILL.md) across Claude Code, Cursor, and Codex — spec compliance, vendor-specific loading behavior, and known quirks. |
Use this skill when working with SKILL.md files — validating format, diagnosing why a skill isn't loading or appearing in the catalog, or understanding vendor-specific behavior differences.
Before validating any skill, validate this one first:
Check that skill-artifact/SKILL.md itself has no metadata, compatibility, or license fields (the Claude Code demotion bug applies to any skill, including this one), and that its description is under 130 chars. If this skill is broken, its validation output cannot be trusted.
Spec validation checklist:
name: required, lowercase a-z 0-9 hyphens only, must match directory namedescription: required, 1–1024 chars, used for catalog discovery — keep under 130 chars for large skill collections- No other frontmatter fields are required by the agentskills.io spec
compatibility, license, metadata fields exist in spec but trigger a loading bug in Claude Code — see vendor-claude reference
Directory layout (agentskills.io):
skill-name/
├── SKILL.md # required
├── references/ # optional: loaded on demand
├── scripts/ # optional: must be chmod +x
└── assets/ # optional: templates, data
Progressive disclosure (all vendors):
- Catalog: name + description only (~50–100 tokens) — always loaded
- Instructions: full SKILL.md body — loaded when agent decides it's relevant or user invokes
- Resources: scripts/, references/, assets/ — loaded on demand when instructions reference them
Invocation syntax by vendor:
- Claude Code:
/plugin-name:skill-name
- Codex:
@plugin-name skill-name
- Cursor:
/plugin-name:skill-name
For vendor-specific loading quirks (metadata demotion bug, context budget limits, extension fields), see the references/ directory.
