claudelint

Appearance

skill-body-word-count ​

SKILL.md body exceeds recommended word count

Warning Configurable

Rule Details ​

This rule counts the words in the body of SKILL.md files (everything after the YAML frontmatter) and warns when the count exceeds a configurable threshold. Anthropic recommends keeping skills concise so AI models can process them efficiently. Lengthy content should be moved to reference files for progressive disclosure, allowing the model to load detailed information only when needed.

Incorrect ​

SKILL.md with a body exceeding 5,000 words

yaml
---
name: my-skill
---

# My Skill

... (5,000+ words of inline content) ...

Correct ​

SKILL.md with concise body and references to external files

yaml
---
name: my-skill
---

# My Skill

Brief overview and core instructions.

For details, see [reference docs](references/details.md).

How To Fix ​

Extract verbose sections, long examples, and reference material into separate files under a references/ directory. Keep the SKILL.md body focused on essential instructions and link to the extracted files.

Options ​

Default options:

json
{
  "maxWords": 5000
}

Allow up to 8,000 words in the body:

json
{
  "maxWords": 8000
}

Enforce a stricter 3,000-word limit:

json
{
  "maxWords": 3000
}

When Not To Use It ​

Disable this rule if your skill requires extensive inline documentation and splitting into reference files would reduce clarity or usability.

Resources ​

Version ​

Available since: v0.3.0