CLAUDE.md@plugins · git:20261020.6c1e9ac · 2026-10-20 · sha256 8013db3393475723
CLAUDE.md@plugins git:20261020.6c1e9acA
Immutable. This exact content never changes and is served at /api/v1/blob/8013db3393475723.
# Plugin Development Guide
Context for developing plugins in the cc-skills marketplace.
**Hub**: [Root CLAUDE.md](../CLAUDE.md) | **Sibling**: [docs/CLAUDE.md](../docs/CLAUDE.md)
## Plugin Discovery (Critical)
**SSoT**: `.claude-plugin/marketplace.json`
Creating a plugin directory without registering it results in "Plugin not found" error.
**Prevention checklist**:
- [ ] Plugin dir exists in `plugins/`
- [ ] Entry added to `.claude-plugin/marketplace.json`
- [ ] `bun scripts/validate-plugins.mjs` passes
- [ ] Pre-commit hook validates
**Detailed Reference**: [Validation Reference](/plugins/plugin-dev/skills/skill-architecture/references/validation-reference.md)
## Creating Plugins
```bash
# Recommended: Auto-registers in marketplace.json
/plugin-dev:create my-plugin
# Manual: Must add marketplace.json entry yourself
mkdir -p plugins/my-plugin/{skills,hooks,commands,scripts}
```
## Plugin Structure
```
plugins/my-plugin/
├── .claude-plugin/plugin.json # Plugin manifest (optional; 2 plugins ship one)
├── README.md # Plugin documentation (user-facing)
├── CLAUDE.md # Per-plugin SSoT for maintainers — invariants, conventions, recent changes
├── skills/ # Skill definitions
│ └── my-skill/
│ ├── SKILL.md # User-invocable skill content (loaded when skill fires)
│ ├── CLAUDE.md # (Optional) per-skill SSoT for maintainers — file table, edit policy,
│ │ # critical invariants, recent-change log. Add when SKILL.md starts
│ │ # mixing "what to do when invoked" with "what to know before editing".
│ └── references/ # Supporting docs (loaded on-demand by SKILL.md)
├── hooks/ # Hook scripts + hooks.json
└── scripts/ # Installation/management
```
**Why both README.md and CLAUDE.md at the plugin level**: README.md is for end-users browsing GitHub; CLAUDE.md is for future Claude sessions (and maintainers) who need to know the load-bearing invariants, recent design decisions, and "don't touch this" rules that don't belong in marketing copy.
## Link Conventions
| Link Target | Format | Example |
| -------------------- | ----------------------- | -------------------------------- |
| Skill-internal files | Relative (`./`, `../`) | `[Guide](./references/guide.md)` |
| Repo docs (ADRs) | Repo-root (`/docs/...`) | `[ADR](/docs/adr/file.md)` |
| External resources | Full URL | `[Docs](https://example.com)` |
**Why**: A plugin's skills are installed under `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/skills/`, and the **version segment changes on every release** — so any absolute path a skill hardcodes is stale by the next update. Relative links resolve against the skill's own directory wherever that lands.
## Shell Compatibility
The Bash tool runs zsh on macOS. Wrap a block in `/usr/bin/env bash` only for syntax zsh does not implement or implements differently. The measured table, including the three silent differences (`BASH_REMATCH`, word splitting, 1-indexed arrays), is in [bash-compatibility.md](/plugins/plugin-dev/skills/skill-architecture/references/bash-compatibility.md).
## Validation
Run before committing:
```bash
bun scripts/validate-plugins.mjs # Validate only
bun scripts/validate-plugins.mjs --fix # Show fix instructions
bun scripts/validate-plugins.mjs --strict # Fail on warnings
```
## Hooks in Plugins
If your plugin includes hooks, see [Hooks Development Guide](/docs/HOOKS.md).
## All Plugins (40)
Each plugin's CLAUDE.md is its own SSoT for purpose, stack, and conventions. Listed alphabetically by directory name; follow the link for details. To verify this list matches reality: `comm -3 <(grep -oE '\[([a-z0-9-]+)\]\(\./[a-z0-9-]+/CLAUDE\.md\)' plugins/CLAUDE.md | sed -E 's/\[([a-z0-9-]+)\].*/\1/' | sort) <(ls -1 plugins/ | grep -v -e node_modules -e CLAUDE.md | sort)` (empty output = aligned).
- [agent-reach](./agent-reach/CLAUDE.md)
- [arxiv-source-first](./arxiv-source-first/CLAUDE.md)
- [asciinema-tools](./asciinema-tools/CLAUDE.md)
- [calcom-commander](./calcom-commander/CLAUDE.md)
- [chrome-profiles](./chrome-profiles/CLAUDE.md)
- [cli-anything](./cli-anything/CLAUDE.md)
- [crucible](./crucible/CLAUDE.md)
- [devops-tools](./devops-tools/CLAUDE.md)
- [doc-tools](./doc-tools/CLAUDE.md)
- [dotfiles-tools](./dotfiles-tools/CLAUDE.md)
- [floating-clock](./floating-clock/CLAUDE.md)
- [garch-volatility-toolkit](./garch-volatility-toolkit/CLAUDE.md) — walk-forward GARCH/GJR vol forecasting; methodology, not an alpha claim (honest negative-to-marginal results)
- [gemini-deep-research](./gemini-deep-research/CLAUDE.md)
- [gh-tools](./gh-tools/CLAUDE.md)
- [git-town-workflow](./git-town-workflow/CLAUDE.md)
- [gmail-commander](./gmail-commander/CLAUDE.md)
- [html-showcase](./html-showcase/CLAUDE.md)
- [itp](./itp/CLAUDE.md)
- [itp-hooks](./itp-hooks/CLAUDE.md)
- [link-tools](./link-tools/CLAUDE.md)
- [macos-font-defaults](./macos-font-defaults/CLAUDE.md)
- [macos-permissions](./macos-permissions/CLAUDE.md)
- [macro-keyboard](./macro-keyboard/CLAUDE.md) — also has skill-level CLAUDE.mds (first plugin to adopt the deeper layer; see [macro-keyboard/CLAUDE.md](./macro-keyboard/CLAUDE.md#skills) for the per-skill table)
- [media-tools](./media-tools/CLAUDE.md)
- [mql5](./mql5/CLAUDE.md)
- [notes-commander](./notes-commander/CLAUDE.md) — includes the `draft-park` skill (formerly the draft-hold plugin)
- [openwolf](./openwolf/CLAUDE.md)
- [orca-tools](./orca-tools/CLAUDE.md)
- [plugin-dev](./plugin-dev/CLAUDE.md)
- [productivity-tools](./productivity-tools/CLAUDE.md)
- [pushover-commander](./pushover-commander/CLAUDE.md)
- [quality-tools](./quality-tools/CLAUDE.md)
- [quant-research](./quant-research/CLAUDE.md)
- [rust-tools](./rust-tools/CLAUDE.md)
- [ssh-tunnel-companion](./ssh-tunnel-companion/CLAUDE.md)
- [statusline-tools](./statusline-tools/CLAUDE.md)
- [tlg](./tlg/CLAUDE.md)
- [unlimited-ocr](./unlimited-ocr/CLAUDE.md)
- [web-forge](./web-forge/CLAUDE.md) — browser automation for API-less operations: console recipes (Google Admin family), node forge scripts, both connection modes, DOM-to-vault secrets, Cloudflare Access walls
- [whatsapp-commander](./whatsapp-commander/CLAUDE.md)
## Toolchain
**Bun-first** for JavaScript globals. See [Root CLAUDE.md](../CLAUDE.md#development-toolchain).
## Related Documentation
- [ITP Plugin CLAUDE.md](/plugins/itp/CLAUDE.md)
- [Marketplace Installation Troubleshooting](/docs/troubleshooting/marketplace-installation.md)