Check AI agent skills folders for
SKILL.mdproblems before they reach your agent.
Agents such as Claude Code, Codex CLI and Cursor discover skills by reading each folder's SKILL.md frontmatter at startup. A broken file does not crash anything, and what happens next depends on the agent: the skill may be skipped, load without its description, or simply never be picked. skills-lint checks skills folders for these problems so you can catch them locally or in CI.
$ npx skills-lint test/fixtures/broken
skills-lint: scanning 1 root(s)
- test/fixtures/broken
checked 3 skill folder(s)
✖ Found 3 issue(s):
[no-skill-md] test/fixtures/broken/ghost-folder
folder has no SKILL.md — this skill will never load
[description] test/fixtures/broken/long-desc/SKILL.md
description is 1121 characters (max 1024) — the skill is silently dropped
[description] test/fixtures/broken/no-desc/SKILL.md
description is missing — the skill is silently droppedStatus: v0.2 checks folder structure and the
descriptionfield against the Agent Skills spec. It does not yet model how each agent loads skills, and some messages overstate the consequences — see Known limitations. Agent-aware checks are being built in the open: roadmap issues.
Each agent treats a broken SKILL.md differently, and none of them stops you from committing one:
- Codex skips a skill whose
descriptionis empty and shows a startup warning ("Skipped loading N skill(s) due to invalid SKILL.md files"). - Claude Code loads a skill whose frontmatter YAML does not parse "with no fields set", and uses the first line of the body when
descriptionis missing (docs) — so the skill may load but never be matched to a request. - Cursor requires
nameanddescription; without a description "the agent is unlikely to pick the skill on its own" (docs).
The Agent Skills spec sets the common ground: name and description are required, and description is at most 1024 characters. Older Codex releases rejected longer descriptions (openai/codex#13941); current releases accept them, but the limit still matters for portability.
skills-lint runs the same checks every time, without starting an agent, so problems are caught in a pull request instead of on someone's machine.
No install needed:
npx skills-lintWith no arguments it looks for the usual skills folders — .agents/, .claude/, .codex/, .cursor/, .zcode/ (each …/skills), in the current directory first, then your home directory — and prints exactly what it scanned. To scan specific folders instead, pass them explicitly:
npx skills-lint <path> [<path> ...]Explicit paths are recommended, especially in CI: auto-detection scans folders that belong to different agents together, which can produce false shadowed findings (see Known limitations).
Machine-readable output:
npx skills-lint --format jsonThe JSON report has this shape. line is present only when a finding points into a file (1-based):
{
"roots": ["/abs/path/.claude/skills"],
"skillsChecked": 3,
"issues": [
{
"rule": "description",
"severity": "error",
"path": "/abs/path/.claude/skills/pdf/SKILL.md",
"line": 3,
"message": "description is 1121 characters (max 1024) — the skill is silently dropped"
}
],
"summary": { "errors": 1, "warnings": 0 }
}To switch a rule off, pass --ignore <rule> (repeatable). An unknown rule name is an error, so a typo cannot silently keep a rule on:
npx skills-lint .claude/skills --ignore sprawled --ignore shadowedEach finding has a severity. Errors fail the run; warnings are reported but never fail it.
| Rule | Severity | Finding |
|---|---|---|
no-skill-md |
error | A folder in a skills root has no SKILL.md |
frontmatter |
error | SKILL.md does not start with a --- block, the block is not closed, is not valid YAML, or is not key: value pairs. An unquoted : inside a value is called out with its line, since Claude Code then loads the skill with no fields set |
frontmatter |
error / warning | The file starts with a UTF-8 BOM, which hides the frontmatter from Codex: an error in folders Codex reads (.agents/skills, .codex/skills), a warning elsewhere |
description |
error | description is missing, is not text (a list or mapping), or is longer than the spec limit of 1024 characters |
shadowed |
error | The same skill name appears in more than one scanned root; the copy in the later root is reported |
reserved-name |
error | A skill folder is named synced (any capitalization) inside .claude/skills; Claude Code reserves that name for skills downloaded from claude.ai and skips it |
sprawled |
warning | Skills are spread across several scanned roots |
Clean folders exit quietly:
$ npx skills-lint .claude/skills
skills-lint: scanning 1 root(s)
- .claude/skills
checked 6 skill folder(s)
✔ No issues foundWhat skills-lint assumes about each agent, generated from src/agents.ts (npx skills-lint --facts prints the same table). Behavior no source documents is marked unknown.
| Fact | Source | Checked |
|---|---|---|
| A skill is a folder containing a file named exactly SKILL.md. | agentskills.io/specification | 2026-10-30 |
name and description are required frontmatter fields. |
agentskills.io/specification | 2026-10-30 |
description is at most 1024 characters. |
agentskills.io/specification | 2026-10-30 |
name is 1–64 characters. |
agentskills.io/specification | 2026-10-30 |
name uses lowercase a-z, 0-9 and hyphens, with no leading, trailing or consecutive hyphens. |
agentskills.io/specification | 2026-10-30 |
name must match the parent folder name. |
agentskills.io/specification | 2026-10-30 |
compatibility is at most 500 characters. |
agentskills.io/specification | 2026-10-30 |
| Keep the SKILL.md body under 500 lines or about 5,000 tokens. | agentskills.io/specification | 2026-10-30 |
| Fact | Source | Checked |
|---|---|---|
Reads .claude/skills in the start directory and every parent up to the repository root. |
code.claude.com/docs/en/skills | 2026-10-30 |
Reads ~/.claude/skills, plus an enterprise managed directory. |
code.claude.com/docs/en/skills | 2026-10-30 |
| On a duplicate name, enterprise wins over personal and personal over project; a project-root skill and a nested skill both load. | code.claude.com/docs/en/skills | 2026-10-30 |
Only <root>/<skill-name>/SKILL.md is documented (one level deep). |
code.claude.com/docs/en/skills | 2026-10-30 |
name defaults to the directory name. |
code.claude.com/docs/en/skills | 2026-10-30 |
~/.claude/skills/synced/ holds skills downloaded from claude.ai; a skill authored under that name (any capitalization) is skipped. |
code.claude.com/docs/en/skills | 2026-10-30 |
anthropic-skills and every anthropic-skills:* name are reserved for synced skills. |
code.claude.com/docs/en/skills#characters-a-skill-name-cant-hold | 2026-10-30 |
Names with zero-width/control, private-use or unassigned characters, bidi controls, any blank other than one plain space between words, or < / > are refused: a folder name stops the skill loading, a frontmatter name makes it uninvocable by that name. |
code.claude.com/docs/en/skills#characters-a-skill-name-cant-hold | 2026-10-30 |
Frontmatter is read only when the opening --- is the file's first line. |
code.claude.com/docs/en/skills | 2026-10-30 |
| On a frontmatter YAML error the skill still loads with no fields set. | code.claude.com/docs/en/skills | 2026-10-30 |
Without description, the first non-empty line of the markdown body is used. |
code.claude.com/docs/en/skills | 2026-10-30 |
description + when_to_use is truncated at 1,536 characters in the skill listing (configurable via skillListingMaxDescChars). |
code.claude.com/docs/en/skills#skill-descriptions-are-cut-short | 2026-10-30 |
| The skill listing budget is 1% of the model's context window; on overflow, descriptions of the least-invoked skills are dropped first. | code.claude.com/docs/en/skills#skill-descriptions-are-cut-short | 2026-10-30 |
| Fact | Source | Checked |
|---|---|---|
Reads .agents/skills from the working directory up to the repository root, and .codex/skills from the project config layer. |
github.com/openai/codex/blob/f752c97/codex-rs/ext/skills/src/host_roots.rs (main @ f752c97) | 2026-10-30 |
Reads ~/.agents/skills, $CODEX_HOME/skills (default ~/.codex/skills, deprecated but still read) and /etc/codex/skills. |
github.com/openai/codex/blob/f752c97/codex-rs/ext/skills/src/host_roots.rs (main @ f752c97) | 2026-10-30 |
| Duplicate names are not merged: both copies can appear in skill selectors. | learn.chatgpt.com/docs/build-skills | 2026-10-30 |
| Each root is walked recursively up to depth 6, at most 2,000 skill folders per root. | github.com/openai/codex/blob/f752c97/codex-rs/ext/skills/src/loader/mod.rs (main @ f752c97) | 2026-10-30 |
A name over 64 characters is rejected. |
github.com/openai/codex/blob/f752c97/codex-rs/skills/src/parser.rs (main @ f752c97) | 2026-10-30 |
name falls back to the folder name; lowercase and the folder match are not enforced. |
github.com/openai/codex/blob/f752c97/codex-rs/skills/src/parser.rs (main @ f752c97) | 2026-10-30 |
description has no length limit (the 1024 limit existed in v0.111.0 and was removed). |
github.com/openai/codex/blob/f752c97/codex-rs/skills/src/parser.rs (main @ f752c97) | 2026-10-30 |
An empty description skips the skill, with a startup warning "Skipped loading N skill(s) due to invalid SKILL.md files." |
github.com/openai/codex/blob/f752c97/codex-rs/tui/src/app/startup_prompts.rs (main @ f752c97) | 2026-10-30 |
A UTF-8 BOM before the opening --- hides the frontmatter. |
github.com/openai/codex/blob/f752c97/codex-rs/skills/src/parser.rs (main @ f752c97) | 2026-10-30 |
| An unquoted colon inside a frontmatter value is repaired before parsing. | github.com/openai/codex/blob/f752c97/codex-rs/skills/src/parser.rs (main @ f752c97) | 2026-10-30 |
| The skill listing budget is 2% of the context window in tokens, or 8,000 characters when the window is unknown; a configured budget is capped at 10,000 tokens. On overflow all descriptions are removed. | github.com/openai/codex/blob/f752c97/codex-rs/ext/skills/src/render.rs (main @ f752c97) | 2026-10-30 |
| Fact | Source | Checked |
|---|---|---|
Reads .agents/skills and .cursor/skills, plus .claude/skills and .codex/skills for compatibility, in the project and under ~. |
cursor.com/docs/context/skills | 2026-10-30 |
| Which copy is used when two skills share a name is not documented. | cursor.com/docs/context/skills | 2026-10-30 |
| The skills root is walked recursively and any SKILL.md is picked up; category folders are organizational. | cursor.com/docs/context/skills | 2026-10-30 |
name must match the parent folder name. |
cursor.com/docs/context/skills | 2026-10-30 |
Without description the agent is unlikely to pick the skill on its own, but it can still be invoked by name. |
cursor.com/docs/context/skills | 2026-10-30 |
| Fact | Source | Checked |
|---|---|---|
No source found for where ZCode reads skills; .zcode/skills is scanned only because v0.2 did. |
none found | 2026-10-30 |
v0.2 is deliberately small, and these are known gaps. Each one has an open issue:
- Not agent-aware yet. All scanned roots are treated as one namespace, in scan order. Agents don't work that way: Claude Code doesn't read
.agents/skills, Codex doesn't read.claude/skills, Claude Code prefers a personal skill over a project skill, and Codex lists both copies of a duplicate name. Soshadowedbetween folders of different agents is usually a false positive. → #3 - Messages overstate consequences. "the skill is silently dropped" is not accurate for every agent (see Why). → #6
- Symlinked skill folders are skipped, including the common layout where skills in
~/.claude/skillslink to~/.agents/skills. → #2 ~/.claude/skills/synced(skills synced from claude.ai) is skipped when it has noSKILL.md, and a user-authored skill under that reserved name is reported. Its downloaded contents are not counted or inspected yet. → #4- Nested category folders (
skills/tools/pdf/SKILL.md), which Codex and Cursor support, are reported as folders withoutSKILL.md. → #14 nameand other fields are not validated yet. → #8, #17
Exit code is 1 when at least one error is found and 0 otherwise (a run with only warnings passes). As a GitHub Action:
- uses: pachara-n/skills-lint@v1
with:
paths: .claude/skills # recommended; auto-detects when omittedOr run it directly:
- run: npx skills-lint .claude/skillsnpm install
npm test # build + unit & integration tests (fixtures in test/fixtures)
npm run build # bundle to dist/ via tsupContributions are welcome — read CONTRIBUTING.md first (claim an issue before you start). Issues labelled good first issue have a scoped starting point.