claude-plugins
CLAUDE.md3 starsChanged 48 days agoMITView on GitHub
Claude Code plugin marketplace by Apurv Bazari. Five plugins — all markdown + shell + JSON, plus one browser script (walkthrough's system-map engine); no compiled code. (onboard, notify, handoff, walkthrough, lens.) Every plugin must have: - .claude-plugin/plugin.json — manifest with name, version, description, author, license, keywords, plus the directory listing fields homepage, documentationUrl, supportUrl, privacyPolicyUrl - README.md — user-facing documentation; Anthropic's directory shows it as the listing description (see below) - LICENSE — a copy of the root LICENSE, because…
- Commits and pushes
In this repository6 other files it gives its agents.
- doc-auditSkill
- feature-doneSkill
- progressive-disclosureSkill
- release-docsSkill
- test-plugins-locallySkill
- validateSkill
The file
We split this CLAUDE.md into the rules it gives an agent
12 rules. About 0 are common, 2 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 50
Every plugin must have:
- Very specific: line 64
No credentials from the environment, no unpinned launchers: Never write a config that reads a token from the user's environment and sends …
- Very specific: line 67
Run claude plugin validate ./<plugin> --strict (CI does, on CLI 2.1.314).
- Very specific: line 110
Run /validate to check all plugins at once
- Very specific: line 114
When referencing Claude Code documentation in any plugin file, use the current home https://code.claude.com/docs/en/*.
- Very specific: line 128
When ready to ship: PR from develop → main (merge commit, never squash)
- Very specific: line 135
Run /release-docs locally to do the same by hand.
- Very specific: line 136
After shipping: merge main back into develop (merge commit) to keep them in sync
- Very specific: line 144
Create <plugin>/ directory with .claude-plugin/plugin.json, README.md, and at least one skill
- Very specific: line 145
Add entry to .claude-plugin/marketplace.json — version must match plugin.json
- Very specific: line 146
Create <plugin>/CONVENTIONS.md documenting internal conventions
- Distinctive: line 147
Follow patterns from existing plugins — use onboard as the most complete reference
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
claude-plugins
Claude Code plugin marketplace by Apurv Bazari. Five plugins — all markdown + shell + JSON, plus one browser script (walkthrough's system-map engine); no compiled code. (onboard, notify, handoff, walkthrough, lens.)
Repository
- GitHub:
ApurvBazari/claude-plugins(public) - Marketplace:
apurvbazari-plugins(registered in.claude-plugin/marketplace.json)
Architecture
.claude-plugin/marketplace.json ← plugin registry
│
├──→ onboard/ ← codebase analyzer + tooling generator
│ ├── skills/ (start, adopt, generate, update, check, verify, evolve,
│ │ research, wizard, generation, maintain)
│ ├── agents/ (codebase-analyzer, config-generator, feature-evaluator,
│ │ research-specialist, research-verifier)
│ ├── scripts/ (detect-{config,dep,structure}-changes, detect-{lsp,mcp}-signals, audit-tooling, install-plugins,
│ │ maintain-{detect,guard,write} + maintain-lib/)
│ └── references/ (plugin-install-consent, ask-user-question-guard, …)
│
├──→ notify/ ← macOS and Linux desktop notifications
│ ├── skills/ (setup, check, uninstall, wizard)
│ └── scripts/ (notify, install-notifier)
│
├──→ handoff/ ← session handoff continuity
│ ├── skills/ (save, pickup, check, discard)
│ ├── hooks/ (hooks.json, session-start.sh) ← announce-only; no variables
│ └── scripts/ (handoff-lib, compute-progress, snooze, archive-active,
│ prune-archive, merge-fm-key)
│
├──→ walkthrough/ ← session or subject → self-contained interactive HTML
│ ├── skills/ (create, update, document, render)
│ │ └── create/references/system-map-engine.js ← in-page layout engine
│ ├── agents/ (system-analyzer, system-verifier) ← read-only, for document's code reading
│ └── references/ (system-reading, ask-user-question-guard) ← shared rules
│
└──→ lens/ ← intent-grounded review companion (brain; renders via walkthrough)
├── skills/ (review, engine, render-review, capability)
├── agents/ (spec-adherence, plan-adherence, correctness,
│ risk-classify, test-gaps, verifier)
└── schemas/ (review-findings)
(runtime: hands off to walkthrough:render; markdown fallback if absent)Plugin Structure Convention
Every plugin must have:
.claude-plugin/plugin.json— manifest with name, version, description, author, license, keywords, plus the directory listing fieldshomepage,documentationUrl,supportUrl,privacyPolicyUrlREADME.md— user-facing documentation; Anthropic's directory shows it as the listing description (see below)LICENSE— a copy of the rootLICENSE, because people who install a plugin receive only its folder- At least one of:
skills/,agents/
Components live at the plugin root, NOT inside .claude-plugin/. Only plugin.json goes in .claude-plugin/.
Directory submission rules
Each plugin folder is submitted to Anthropic's plugin directory on its own (pre-submission checklist). Keep these true:
- Self-contained. Nothing a plugin loads may point outside its folder. Never cite repo-root files such as
.claude/rules/*.mdfrom a skill, agent or reference; ship a copy in the plugin'sreferences/instead (e.g.<plugin>/references/ask-user-question-guard.md). - Hook scripts stay plain. Every plugin here is a subfolder of the repo, so a script that a hook runs must use no shell variables other than
${CLAUDE_PLUGIN_ROOT}, no$(…), and no calls to other files. Anything else is held for a reviewer. Put real logic in a skill-invoked script instead (seehandoff/hooks/session-start.sh). - No credentials from the environment, no unpinned launchers. Never write a config that reads a token from the user's environment and sends it to a server, and never emit an unpinned
npx/uvxcommand, even into generated project files. - README top section, in this order: one-line tagline, a Works in line (Claude Code / Cowork / claude.ai chat, per the platform-support table), install (directory and this marketplace), what it does, commands, What it reads, writes, and sends (verified against the code), where it works, then detail, then license. Every non-anchor link absolute (
https://github.com/ApurvBazari/claude-plugins/blob/main/...); never write an image path in backticks. - Icon and display name.
assets/icon.png, square, 512–2048 px, under 2 MB (the directory rejects SVG), referenced as"icon": "./assets/icon.png", plus adisplayNameinplugin.json(relabel withdisplayName, never by changingname). The directory captures it once, at the first portal save, so it must exist before a plugin is first submitted. Keep the SVG source beside it. - Run
claude plugin validate ./<plugin> --strict(CI does, on CLI 2.1.314).
Skills are the authoring form for all user-facing entrypoints and internal orchestration. Legacy commands/ directories are no longer used — per Claude Code docs, commands have been merged into skills. A file at commands/<name>.md and a skill at skills/<name>/SKILL.md both create the /<plugin>:<name> slash entry, but only skills support frontmatter (user-invocable, disable-model-invocation), reference directories, and model-driven auto-invocation.
File Type Conventions
| Type | Pattern | Key requirements |
| Skills | skills/<name>/SKILL.md | YAML frontmatter (name, description, optional user-invocable/disable-model-invocation), H1 title, Guard section (if applicable), numbered steps, Key Rules section |
| Agents | agents/<name>.md | H1 name, Tools section, Instructions with numbered steps, Output Format |
| Shell scripts | scripts/<name>.sh | #!/usr/bin/env bash, set -euo pipefail, ShellCheck-clean, POSIX compat |
| Manifests | .claude-plugin/plugin.json | Required: name, version, description, author, license, keywords |
| References | skills/<name>/references/*.md (skill-owned) or <plugin>/references/*.md (plugin-flat) | Supporting docs loaded by skill or agent instructions. Colocate with the skill that loads it; when the consumer is an agent, use the plugin's flat references/ home. Never agents/**/references/ — Claude Code registers every .md under agents/ as a dispatchable agent, so a reference parked there becomes a phantom agent (<plugin>:references:<file>) and fails claude plugin validate. check-references.sh walks both valid homes and rejects the agents/ one. |
Skill Frontmatter Categories
Apply the right invocation policy per skill:
| Category | Who invokes | Frontmatter | Examples |
| Destructive / setup | User only (explicit) | disable-model-invocation: true | onboard:start, onboard:update, notify:setup, notify:uninstall |
| Read-only helpers | User + auto | (default) — write a specific description | onboard:check, notify:check |
| Writing helpers | User + auto | (default) — the description must say what the skill writes; never install anything without an accepted, named offer | onboard:verify, onboard:evolve |
| Programmatic API | Claude only, hidden | user-invocable: false | onboard:generate |
| Internal building blocks | Claude only, hidden | user-invocable: false | wizard, generation |
Canonical frontmatter spelling is hyphenated (user-invocable, disable-model-invocation) per the Claude Code docs. Underscore spelling is silently ignored.
Frontmatter must parse as YAML. A plain value can't contain : , so wrap a description that has one in double quotes. Claude Code and claude plugin validate --strict both accept the broken form, but Anthropic's plugin directory holds the version (it held lens 1.5.3). tests/test_frontmatter_yaml.sh enforces this for every shipped skill and agent.
Naming Conventions
- File names: kebab-case (
codebase-analyzer.md,validate-bash.sh) - Plugin directories: lowercase (
onboard,notify,handoff) - Manifest names: match directory name
- References: always in a
references/subdirectory owned by their consumer — inside the skill (skills/<name>/references/) for skill-loaded docs, or the plugin's flat<plugin>/references/for agent-loaded docs. Never underagents/— everything there is registered as an agent. - Skill
namefrontmatter: lowercase letters, numbers, hyphens only (max 64 chars). If omitted, derives from the directory name.
Quality Checks
- ShellCheck on all
.shscripts:shellcheck scripts/*.sh - JSON validation on manifests: verify required fields in plugin.json + marketplace.json
- Reference integrity: every file referenced in skills/agents must exist
- Run
/validateto check all plugins at once
Documentation URL convention
When referencing Claude Code documentation in any plugin file, use the current home https://code.claude.com/docs/en/*. The legacy https://docs.anthropic.com/en/docs/claude-code/* URLs 301-redirect and waste turns when programmatic WebFetch calls don't follow redirects (release-gate finding A6, 2026-04-16).
Git Discipline
- Conventional commits:
type(scope): description— types:feat,fix,refactor,docs,chore - Branch naming:
type/short-description(e.g.,feat/notify-setup,fix/notify-subtitle) - One logical change per commit — don't mix plugin changes across plugins
- Scope = plugin name when change is plugin-specific (e.g.,
feat(onboard): add verify skill)
Branching & Release
Two branches: develop (integration) and main (release). main is the GitHub default branch — it is what the published marketplace serves, so a fresh /plugin marketplace add ApurvBazari/claude-plugins installs released code, not in-flight work.
- Feature branches → PR to
develop(squash merge). Pass--base developexplicitly —gh pr createtargetsmainby default now. - When ready to ship: PR from
develop→main(merge commit, never squash) Docs ship with the release. Opening or updating the
develop→mainPR runsrelease-docs.yml:- it detects the docs obligations the release leaves open (stale badges and counts, new CHANGELOG entries not yet documented, retired names). When there are none, it stops;
- otherwise it dispatches the docs bot on
develop. The bot runs/release-docs mode=ciunattended, in a job with no publishing credentials. A separate job that never runs the model applies the bot's patch to a fresh checkout, re-runs the deterministic post-checks, and opens adocs/release-sync-*PR todevelop, linked on the release PR. A failed check makes that PR a draft labelledneeds-owner; - review the docs PR and squash-merge it. The release PR then refreshes and detects again;
- the required Docs Obligations check (
validate.yml) blocks the merge tomainuntil the docs match.
Run
/release-docslocally to do the same by hand. Coverage is declared in.github/docs-ledger.json, andwaivedis owner-only.- After shipping: merge
mainback intodevelop(merge commit) to keep them in sync
Version bumps are manual — bump plugin.json + marketplace.json + CHANGELOG.md in the feature PR. No release-please or automated version management.
Squash-merging develop→main causes permanent divergence — the two branches lose their shared history and can never cleanly sync again.
Adding a New Plugin
- Create
<plugin>/directory with.claude-plugin/plugin.json,README.md, and at least one skill - Add entry to
.claude-plugin/marketplace.json— version must match plugin.json - Create
<plugin>/CONVENTIONS.mddocumenting internal conventions - Follow patterns from existing plugins — use onboard as the most complete reference
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

