claude-plugin-readme

Plugin should have a README.md file

Formerly known as plugin-readme. The legacy name still works in configs, --rule/--skip-rule, suppression comments, and baselines.

Severity	warning (auto)
Autofix	-
Since	v0.1.0
Repo Types	marketplace, single-plugin
Category	Claude Code

Why

A README.md in the plugin directory provides human-readable documentation for users browsing the repository or marketplace. Without it, users must read the plugin.json and command files to understand what the plugin does.

Examples

Bad:

my-plugin/
  .claude-plugin/
    plugin.json

Good:

my-plugin/
  README.md
  .claude-plugin/
    plugin.json

How to fix

Create a README.md file in the plugin's root directory explaining what the plugin does, how to install it, and how to use its commands.

Codex plugins

This is a Claude-format convention. A directory claimed only by OpenAI Codex — a .codex-plugin/plugin.json, or a local-source listing in a Codex catalog, with no .claude-plugin marker or Claude marketplace listing — is exempt: its README conventions belong to its own ecosystem, not to Claude's marketplace display. A dual-manifest directory keeps this check, and the ecosystem-neutral content and security rules read every plugin's files regardless of provenance.

Configuration

rules:
  claude-plugin-readme:
    enabled: auto  # true | false | auto
    severity: warning

Run skillsaw explain claude-plugin-readme to see this documentation and the rule's effective configuration in your terminal.