AXC-D024: Skill description over 1,024 characters

The description in the SKILL.md frontmatter is longer than the 1,024 characters the Agent Skills specification allows. A loader that enforces the limit may reject the skill or cut the description, and a cut loses the end of the text, where a “when to use it” sentence may sit. Even where it is accepted, the description is loaded for every installed skill, so extra length costs context all the time.

What it checks

ax-check measures the length of the frontmatter description of each SKILL.md and reports any longer than 1,024 characters.

Why it matters

The Agent Skills specification sets a maximum of 1,024 characters for description. Anthropic’s skill authoring guidance (vendor guidance) gives the same maximum and adds that the description “is injected into the system prompt”. The description’s job is discovery: say what the skill does and when to use it, so the agent can decide whether to load the body. Instructions, examples and reference material belong in the body or in bundled files, which load only when the skill is used.

How to fix

• Cut the description to two parts: what the skill does, and when to use it (and, if useful, when not to).
• Move steps, examples, option lists and background into the SKILL.md body.
• Move long reference material into files under references/ and link to them from the body.

Example

Before

---
name: invoice-review
description: >
  Checks a draft invoice before it is sent. First open the invoice and read
  every line item, then compare each line with the order, then check the tax
  rate for the customer's country using the table below, then check the due
  date against the payment terms ... (a tax table and 12 more steps follow,
  1,400 characters in total)
---

After

---
name: invoice-review
description: Checks a draft invoice before it is sent, covering totals, tax and due dates. Use this when asked to review, check or approve an invoice. Do not use it to create invoices.
---

# Invoice review

1. Open the draft invoice and read every line item.
2. Compare each line with the order.
3. Check the tax rate in [the tax table](references/tax-rates.md).

How ax-check detects it

ax-check takes the description value as the YAML parser returns it and counts its characters. A folded or literal block scalar is measured after YAML has joined its lines. The value is not trimmed first.

What it ignores: a missing description is reported by AXC-D022, not here. A long description that is still under the limit is not reported by this rule; AXC-D016 reports descriptions that are far longer than the others in the same set of skills.

Known false positives: ax-check counts characters as JavaScript string units, so an emoji or another character outside the Basic Multilingual Plane counts as two. A description just under the limit that uses many such characters may be reported.

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

Sources

• Specification: Agent Skills specification, agentskills.io, retrieved 2026-10-08. https://agentskills.io/specification. description is required, non-empty, at most 1,024 characters, and “Describes what the skill does and when to use it.”
• Vendor guidance: Skill authoring best practices, Anthropic, retrieved 2026-10-08. https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices. Description maximum 1,024 characters; “The description is injected into the system prompt.”

Related evidence

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.

• EV-0017: Injected skills lowered pass rates and raised token cost on average (Preprint). WebDev-Skills-Bench (preprint) found that injecting matched public skills reduced mean Pass@2 by 1.3% to 4.2% across four models and raised token cost by 72% to 394%, with gains in only 17% to 36% of skill-project pairs.
• EV-0018: Skill rules that name a command or path change what agents do (Preprint). A study of 3,159 skills (preprint) found that adding a checkable rule raised the rate at which four coding agents took the required action by +0.23 on average, with the gain coming mainly from rules naming a command or path the old skill did not mention.
• EV-0019: Skill selection precision collapses as the skill pool grows (Preprint). A preprint reports that as the pool of available skills grew from 5 to 100, the precision with which agents actually used the right skill fell from 29.6% to 3.3%.
• EV-0022: Search-and-execute meta-tools cut catalogue tokens by 99% in production (Preprint). PayPal authors report (preprint) that exposing two meta-tools, search and execute, over 2,000+ MCP tools cut tool-token consumption in production from 140.2k tokens (70.1% of context) to 1.3k tokens (0.8%).
• EV-0027: A capable agent skipped the index and guessed the page (Preprint). A preregistered ablation on a 709-page Markdown wiki (preprint) found that a capable tool-using agent never loaded the compact catalogue index, inferring page paths from the question instead, while retrieval-based access kept answer quality non-inferior and cut cost by about a third to over half.
• EV-0030: Adding the context7 MCP server gave no lift; its tools went unused (Vendor measurement). Microsoft reports that adding the context7 MCP server to an anti-hallucination skill gave no meaningful lift on an SPFx upgrade: its tools did not load in 3 of 5 runs and were not called in the other 2, while telling the agent to use CLI for Microsoft 365 raised configuration correctness from 30/80 to 75/80.

Related guides

• Write agent-readable documentation
• Agent tool catalogues need a pruning strategy