# Plugin Conventions

> Structural rules and conventions for authoring installable plugins in the claude-config marketplace. Use when creating or modifying anything under plugins/.

- Skill: `ven0m0/plugin-conventions` (Agent Skill)
- Install (CLI): `npx skillmds add ven0m0/plugin-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ven0m0/plugin-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Ven0m0 (https://skillmd.com/u/ven0m0)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ven0m0/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
```