ax-check rule

AXC-D023: Skill name breaks the naming rules

The skill name is longer than 64 characters, is not lowercase letters, digits and single hyphens, or does not match its folder.

ax-check is a checker being prepared for release. This page documents the rule ahead of that release; see all 50 rules.

Severityerror
KindConformance. A finding is a fact about the input.
Modeax-check lint
Applies toSKILL.md
Pattern tagsskills, discovery
Fix in one lineUse a lowercase, hyphenated name of at most 64 characters that matches the skill folder name.

The skill’s name breaks the rules in the Agent Skills specification. It is longer than 64 characters, uses characters other than lowercase letters, digits and single hyphens, or does not match the folder that holds SKILL.md. Tools that install, list or load skills rely on these rules, so a skill that breaks them may be renamed, rejected or loaded under a name the author did not expect.

What it checks

For each SKILL.md with a name in its frontmatter, ax-check checks that the name:

  • is at most 64 characters long;
  • uses only lowercase letters, digits and hyphens;
  • does not start or end with a hyphen and has no two hyphens in a row;
  • matches the name of the folder that contains SKILL.md.

Why it matters

The Agent Skills specification sets these rules: the name is required, at most 64 characters, made of lowercase letters, numbers and hyphens, must not start or end with a hyphen, must not contain consecutive hyphens, and must match the parent directory name.

The name is how a skill is referred to: in listings, in instructions that say “use the invoice-review skill”, and on disk. When the frontmatter name and the folder name differ, an installer that copies the folder and an agent that reads the frontmatter can end up using two different names for one skill. Mixed case and spaces cause similar mismatches on case-sensitive file systems and in commands.

How to fix

  • Use a short, lowercase, hyphenated name of at most 64 characters, for example invoice-review.
  • Rename the folder or the name field so the two are identical.
  • If you rename a published skill, update any instructions that mention the old name.

Example

Before

skills/invoice-review/SKILL.md

---
name: Invoice_Review--Helper
description: Checks a draft invoice before it is sent. Use this when asked to review an invoice.
---

After

skills/invoice-review/SKILL.md

---
name: invoice-review
description: Checks a draft invoice before it is sent. Use this when asked to review an invoice.
---

How ax-check detects it

ax-check trims the name value and tests it against three conditions:

  • length: more than 64 characters is reported;
  • characters: the name must match the pattern ^[a-z0-9]+(-[a-z0-9]+)*$, which allows only the ASCII letters a to z, the digits 0 to 9 and single hyphens between them;
  • folder: when ax-check knows the folder that contains SKILL.md, the name must equal the folder name exactly.

All problems with one name are reported together in a single finding.

What it ignores: a missing name is reported by AXC-D022, not here. From the command line, ax-check always reads the folder that holds each SKILL.md. The folder check is skipped only when the ax-check library is given the text of a SKILL.md without its folder.

Known false positives: the pattern accepts only ASCII letters. A name with accented or other non-ASCII lowercase letters is reported even if a particular skill loader accepts it.

If the finding does not apply, silence it with --disable AXC-D023.

Sources

  • Specification: Agent Skills specification, agentskills.io, retrieved 2026-10-08. https://agentskills.io/specification. name is required, at most 64 characters, lowercase letters, numbers and hyphens, must not start or end with a hyphen, must not contain consecutive hyphens, and must match the parent directory name.

Records in the AX evidence register that share a pattern tag with this rule. A shared tag means the record is about the same pattern, not that it tests this rule. Read the evidence class before the number.