agentleFS
ApurvBazariApurvBazari/claude-plugins/CLAUDE.md

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

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
  1. Distinctive:

    Every plugin must have:

    line 50
  2. Very specific:

    No credentials from the environment, no unpinned launchers: Never write a config that reads a token from the user's environment and sends …

    line 64
  3. Very specific:

    Run claude plugin validate ./<plugin> --strict (CI does, on CLI 2.1.314).

    line 67
  4. Very specific:

    Run /validate to check all plugins at once

    line 110
  5. Very specific:

    When referencing Claude Code documentation in any plugin file, use the current home https://code.claude.com/docs/en/*.

    line 114
  6. Very specific:

    When ready to ship: PR from develop → main (merge commit, never squash)

    line 128
  7. Very specific:

    Run /release-docs locally to do the same by hand.

    line 135
  8. Very specific:

    After shipping: merge main back into develop (merge commit) to keep them in sync

    line 136
  9. Very specific:

    Create <plugin>/ directory with .claude-plugin/plugin.json, README.md, and at least one skill

    line 144
  10. Very specific:

    Add entry to .claude-plugin/marketplace.json — version must match plugin.json

    line 145
  11. Very specific:

    Create <plugin>/CONVENTIONS.md documenting internal conventions

    line 146
  12. Distinctive:

    Follow patterns from existing plugins — use onboard as the most complete reference

    line 147

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 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 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/*.md from a skill, agent or reference; ship a copy in the plugin's references/ 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 (see handoff/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/uvx command, 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 a displayName in plugin.json (relabel with displayName, never by changing name). 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

TypePatternKey requirements
Skillsskills/<name>/SKILL.mdYAML frontmatter (name, description, optional user-invocable/disable-model-invocation), H1 title, Guard section (if applicable), numbered steps, Key Rules section
Agentsagents/<name>.mdH1 name, Tools section, Instructions with numbered steps, Output Format
Shell scriptsscripts/<name>.sh#!/usr/bin/env bash, set -euo pipefail, ShellCheck-clean, POSIX compat
Manifests.claude-plugin/plugin.jsonRequired: name, version, description, author, license, keywords
Referencesskills/<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:

CategoryWho invokesFrontmatterExamples
Destructive / setupUser only (explicit)disable-model-invocation: trueonboard:start, onboard:update, notify:setup, notify:uninstall
Read-only helpersUser + auto(default) — write a specific descriptiononboard:check, notify:check
Writing helpersUser + auto(default) — the description must say what the skill writes; never install anything without an accepted, named offeronboard:verify, onboard:evolve
Programmatic APIClaude only, hiddenuser-invocable: falseonboard:generate
Internal building blocksClaude only, hiddenuser-invocable: falsewizard, 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 under agents/ — everything there is registered as an agent.
  • Skill name frontmatter: lowercase letters, numbers, hyphens only (max 64 chars). If omitted, derives from the directory name.

Quality Checks

  • ShellCheck on all .sh scripts: 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 /validate to 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 develop explicitly — gh pr create targets main by default now.
  • When ready to ship: PR from develop → main (merge commit, never squash)
  • Docs ship with the release. Opening or updating the develop → main PR runs release-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=ci unattended, 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 a docs/release-sync-* PR to develop, linked on the release PR. A failed check makes that PR a draft labelled needs-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 to main until the docs match.

    Run /release-docs locally to do the same by hand. Coverage is declared in .github/docs-ledger.json, and waived is owner-only.

  • After shipping: merge main back into develop (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

  1. Create <plugin>/ directory with .claude-plugin/plugin.json, README.md, and at least one skill
  2. Add entry to .claude-plugin/marketplace.json — version must match plugin.json
  3. Create <plugin>/CONVENTIONS.md documenting internal conventions
  4. Follow patterns from existing plugins — use onboard as the most complete reference

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.