Plugin Conventions

Plugin Conventions

Each plugin lives under plugins/<name>/ and must contain:

• README.md — purpose, slash commands exposed, install instructions
• PLUGIN.md or plugin.json — machine-readable manifest
• tests/ — at least one test file appropriate to the plugin's language

Directory Rules

• Python-heavy plugins: pyproject.toml at plugin root, tests run via uv run pytest plugins/<name>/tests/
• Shell-heavy plugins: tests use bats (*.bats), run via bats plugins/<name>/tests/
• JS plugins: test file at test.js, run via node plugins/<name>/test.js
• Multi-language: Makefile with test and lint targets; run via make -C plugins/<name> test

Manifest Fields

Required in plugin manifest:

• name — matches directory name exactly
• version — semver
• description — one sentence, no trailing period
• commands — list of slash commands this plugin provides

Naming

• Plugin directory: kebab-case
• Exposed slash commands: /kebab-case
• Python modules inside plugin: snake_case.py
• Hook scripts: snake_case.{py,sh,js}

Validation

Run after any plugin change:

uv tool run "claudelint@0.3.3" --strict plugins/<name>/
node plugins/plugin-validator/test.js