Skill format

Skilldex does not define its own format. It validates skills against the skill format specification that agents such as Claude Code already read: a directory with a SKILL.md at its root, plus optional resource folders.

Directory structure

my-skill/
├── SKILL.md          ← required: frontmatter + instructions
├── scripts/          ← optional: code the skill runs
├── references/       ← optional: documents loaded into context when needed
└── assets/           ← optional: templates, images, fonts

Only scripts/, references/, and assets/ are recognised; any other folder is a warning. Keep executable files (.sh, .py, .js, .ts, .rb) in scripts/ and documents in references/. Put documentation in SKILL.md or references/, not a README.md inside the skill.

SKILL.md

SKILL.md starts with YAML frontmatter between --- lines, followed by the instructions in markdown.

---
name: log-triage
description: "Triage application logs and stack traces to find the root cause of a failure. Use this skill when investigating a bug, a production incident, or a crash, and when the user shares logs, traces, or error output and asks what went wrong."
tags: [debugging, logs]
---

# Log triage

Instructions the agent follows...

Frontmatter

| Field | Required | Rules | |---|---|---| | name | Yes | Kebab-case. Cannot contain claude or anthropic | | description | Yes | What the skill does and when to use it. At least 30 words, at most 1,024 characters, no XML tags | | version, tags, author | No | Metadata; not scored |

The description is what an agent reads to decide whether to use the skill, so a vague one means the skill rarely gets used. Quote it: an unquoted description containing a colon breaks the YAML, and a skill with unreadable frontmatter scores 0.

Length

Keep SKILL.md under 500 lines. Over 400 is a warning; over 500 earns no points for the check. Move long material into references/.

Referenced files

Paths in SKILL.md that point into the skill — a markdown link to assets/template.docx, or a mention of scripts/setup.sh — must exist. Each missing one is an error on the line that references it. External URLs are not checked.

Validate

skillpm validate ./my-skill

skillpm init scaffolds a SKILL.md that already passes. See Quality scoring for how the score is calculated.