claude-plugins

Claude Code plugin collection providing skills and agents for development workflows.

Project Structure

<plugin-name>/
├── .claude-plugin/
│   └── plugin.json      # Plugin manifest (see .claude/rules/plugin-structure.md)
├── README.md            # Plugin documentation
├── CHANGELOG.md         # Auto-generated by release-please
├── skills/
│   └── <skill-name>/
│       ├── SKILL.md     # Skill definition (user-invocable and auto-discovered)
│       └── workflows/   # Bundled *.workflow.js templates (optional)
└── agents/              # Agent definitions (optional)

Rules

Rule clusters and the owner of each shared fact: docs/rules-map.md.

Auditing these docs: docs/audits/README.md records the Layer 1 (automated, monthly) / Layer 2 (quarterly + milestone-triggered) cadence and holds past findings artifacts.

Authoring Skills and Plugins

Invoke /marketplace-authoring — it carries the create-a-skill and create-a-user-invocable-skill frontmatter shapes, the seven metadata files a plugin add/delete must touch, and the development workflow. All four are procedures with a clear trigger, so they live in a skill rather than here (#2140).

Agentic Optimization

See .claude/rules/agentic-optimization.md for detailed patterns.

Key principles:

• Compact output: --dots, --reporter=github, -c
• Fail fast: --bail=1, -x
• CI modes: --reporter=junit, --frozen-lockfile
• Machine-readable: JSON output when available

Plugin Organization

Git Workflow

CRITICAL: Commits and PR titles MUST follow conventional commit format.

Conventional Commits

All commits and PR titles must follow the pattern:

<type>(<scope>): <subject>

Why: This drives release-please version automation and maintains clean git history.

• Commits: Use git commit -m "feat(plugin): description" with issue references
• PR titles: MUST match conventional format - used as commit message on squash-merge
• Scope: The plugin directory name (e.g., feat(git-plugin)). It is a changelog label only; the files touched decide which packages release
• Types: feat, fix, perf, refactor, docs, test, ci, build, chore, revert

See .claude/rules/conventional-commits.md for complete guide and examples.

Example Workflow

# Write and test code
git add src/feature.ts tests/feature.test.ts

# Commit with conventional format + issue reference
git commit -m "feat(git-plugin): add new workflow

Closes #42
Refs #99"

# PR title must also be conventional
gh pr create --title "feat(git-plugin): add new workflow"

Local-model export

Run this marketplace's skills inside other coding agents: two local-model harnesses through the adapter, and Antigravity CLI through in-place skills.json registration (not an adapter):

pi and OpenCode load Claude Code SKILL.md unmodified but neither budgets the skill listing: pi costs ~111 tok/skill and OpenCode ~88 (measured 2026-08-24 — ~34,000 standing tokens for 382 skills), both uncapped. The adapter (ADR-0022) closes that gap for each: a search_skills pull tool + per-turn ranked top-k push injection reaching all ~400 skills at ~600 standing tokens — see adapters/README.md. Antigravity's standing skill-listing cost has not been measured.

Both cutovers are done. pi's curated tier installer (pi/tiers.yaml + scripts/install-pi.sh, ~9,900 standing tokens over ~95 skills) was removed in #2093; OpenCode's rulesync export was retired in #2094, once its own token calibration landed beside the retrieval gate frozen at main_hit_at_k_min = 0.57 on 2026-07-22 (adapters/CUTOVER.md §1 and §8). just export-opencode survives for the two surfaces the adapter does not cover — subagents (OpenCode does not auto-load ~/.claude/agents/) and hooks (OpenCode has no hook surface at all).

Blueprint (constrained dogfooding)

This repo runs blueprint-plugin against itself in a deliberately constrained mode. State lives in docs/blueprint/; see docs/blueprint/README.md for the full rationale.

Always run /blueprint:sync-ids with --dry-run first. Each disabled task carries a context.disabled_reason in the manifest — read it before flipping any flag back on.

Autonomy level 3 is consumer-only (ADR-0020, #2005). This repo stays at automation.autonomy_level: 1 and never runs the level-3 out-of-band pipeline. /blueprint:autonomy-level3 scaffolds that pipeline (the blueprint-autorun + blueprint-wo-execute workflow templates + gate/parser scripts) into a downstream consumer repo that opts in; it is authored and tested here but not exercised here.

Commit-scope convention for blueprint work

What keeps dogfooding from publishing the plugin is the chore type (no bump) plus keeping edits under docs/blueprint/ — not the blueprint scope. release-please routes by files touched, not by scope (.claude/rules/conventional-commits.md), so fix(blueprint): … on a file inside blueprint-plugin/ would publish.

Conventions

• Skill names: lowercase-hyphenated (bun-development)
• Skill invocation: lowercase with colons for nesting (/bun:install)
• Plugin names: suffix with -plugin (typescript-plugin)
• Use tables for quick reference (flags, options)
• Include both short and long flag forms where applicable