skill-readme-forbidden

Skills must use SKILL.md, not README.md

Error

Rule Details

Anthropic explicitly requires skills to use SKILL.md as their primary documentation file, not README.md. Having both files creates ambiguity about which one is the source of truth for the skill definition. This rule checks whether a README.md exists in the same directory as a SKILL.md and reports an error if found. If a skill has complex documentation needs, consolidate all content into SKILL.md rather than splitting across multiple files.

Incorrect

Skill directory containing both SKILL.md and README.md

my-skill/
  SKILL.md
  README.md
  run.sh

Correct

Skill directory with only SKILL.md

my-skill/
  SKILL.md
  run.sh

How To Fix

Remove the README.md file from the skill directory. Migrate any useful content from README.md into SKILL.md.

Options

This rule does not have any configuration options.

Related Rules

• skill-referenced-file-not-found
• skill-too-many-files
• skill-deep-nesting

Resources

• Rule Implementation
• Rule Tests

Version

Available since: v0.3.0