created	2025-12-20
modified	2026-04-16
reviewed	2026-04-16

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)
└── agents/              # Agent definitions (optional)

Rules

Rule	Purpose
`.claude/rules/conventional-commits.md`	Commit and PR title format standards - drives release-please automation
`.claude/rules/plugin-structure.md`	plugin.json schema and directory layout
`.claude/rules/release-please.md`	Version management and changelog automation
`.claude/rules/skill-development.md`	Skill creation patterns
`.claude/rules/agentic-optimization.md`	CLI output optimization for AI
`.claude/rules/skill-naming.md`	Skill namespace conventions
`.claude/rules/shell-scripting.md`	Safe shell patterns and frontmatter extraction
`.claude/rules/agentic-permissions.md`	Granular tool permissions for skills
`.claude/rules/skill-quality.md`	Skill size limits, required sections, and quality checklist
`.claude/rules/skill-execution-structure.md`	Imperative execution patterns for user-invocable skills
`.claude/rules/handling-blocked-hooks.md`	How to respond when hooks block commands
`.claude/rules/hooks-reference.md`	Complete hook event reference (2.1.50+): all events, schemas, timeouts, PermissionRequest
`.claude/rules/prompt-agent-hooks.md`	When to use prompt/agent hooks — decision tree, config schema, prompts guide
`.claude/rules/agent-development.md`	Agent configuration, isolation, background execution, memory, and teams
`.claude/rules/skill-fork-context.md`	When to set `context: fork` and `agent:` on skills
`.claude/rules/regression-testing.md`	Required: add a script check for every skill bug fixed
`.claude/rules/sandbox-guidance.md`	Sandbox constraints, `CLAUDE_CODE_REMOTE` detection, and remote/local skill patterns
`.claude/rules/plugin-flow-diagrams.md`	When and how to add Mermaid flow diagrams

Creating New Skills

See .claude/rules/skill-development.md for detailed patterns.

Quick Start

Create skill directory: mkdir -p <plugin>/skills/<skill-name>

Create skill.md with YAML frontmatter:

---
name: <Skill Name>
description: <1-2 sentence description>
allowed-tools: Bash, Read, Grep, Glob, TodoWrite
created: YYYY-MM-DD
modified: YYYY-MM-DD
reviewed: YYYY-MM-DD
---

Follow content structure: Core Expertise → Commands → Patterns → Quick Reference
Include agentic optimizations table
Update all metadata files (see Plugin Lifecycle section)

Skill Granularity Decision

Choose...	When...
Single skill	Operations are related and share context
Multiple skills	Distinct workflows, different user intents

Example: bun-package-manager (deps) vs bun-development (run/test/build)

Creating User-Invocable Skills

Skills are invocable via /plugin:skill-name syntax. See .claude/rules/skill-naming.md for naming conventions.

Create skill directory: mkdir -p <plugin>/skills/<skill-name>

Create SKILL.md with YAML frontmatter:

---
name: <skill-name>
description: What it does. Use when...
args: <arg-spec>
allowed-tools: Bash, Read
argument-hint: human hint
created: YYYY-MM-DD
modified: YYYY-MM-DD
reviewed: YYYY-MM-DD
---

Include: Context → Execution → Post-actions

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

Plugin Type	Example	Contains
Tool-focused	`tools-plugin`	CLI tool skills (fd, rg, jq)
Language-focused	`typescript-plugin`	Language ecosystem skills
Workflow-focused	`git-plugin`	Git/GitHub operations
Infrastructure	`configure-plugin`	Configuration automation

Plugin Lifecycle

Files to Update

When creating, modifying, or deleting a plugin, update these files:

File	Location	Action
`plugin.json`	`<plugin>/.claude-plugin/plugin.json`	Create/update plugin manifest
`README.md`	`<plugin>/README.md`	Create/update plugin documentation
`marketplace.json`	`.claude-plugin/marketplace.json`	Add/update/remove plugin entry
`release-please-config.json`	Root	Add/remove plugin package config
`.release-please-manifest.json`	Root	Add/remove plugin version entry
`PLUGIN-MAP.md`	`docs/PLUGIN-MAP.md`	Add/remove plugin from navigation map

Creating a New Plugin

Create plugin directory structure (see Project Structure above)
Create .claude-plugin/plugin.json with required fields
Create README.md with plugin documentation

Add entry to .claude-plugin/marketplace.json (under the plugins array):

{
  "name": "new-plugin",
  "source": "./new-plugin",
  "description": "Plugin description",
  "version": "1.0.0",
  "keywords": ["keyword1", "keyword2"],
  "category": "category-name"
}

Note: marketplace.json has structure { "name": "...", "plugins": [...] } — add to the plugins array.

Add to release-please-config.json:

"new-plugin": {
  "component": "new-plugin",
  "release-type": "simple",
  "extra-files": [
    {"type": "json", "path": ".claude-plugin/plugin.json", "jsonpath": "$.version"}
  ],
  "changelog-sections": [
    {"type": "feat", "section": "Features"},
    {"type": "fix", "section": "Bug Fixes"},
    {"type": "perf", "section": "Performance"},
    {"type": "refactor", "section": "Code Refactoring"},
    {"type": "docs", "section": "Documentation"}
  ]
}

Add to .release-please-manifest.json:
```
"new-plugin": "1.0.0"
```

Deleting a Plugin

Remove plugin directory
Remove entry from .claude-plugin/marketplace.json
Remove package from release-please-config.json
Remove version from .release-please-manifest.json

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: Plugin or feature name (e.g., feat(git-plugin), fix(skill-development))
Types: feat, fix, perf, refactor, docs, test, ci, build, chore

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"

Development Workflow

Research documentation - Use context7, web search
Plan skill structure - Decide granularity, scope
Write skills - Follow standard structure
Update all metadata files - See Plugin Lifecycle section
Commit early - Use conventional commit format (see Git Workflow section)
Test - Verify skills load and work
Create PR - Use conventional commit format for title (drives automation)

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.

Task	Status	Why
`adr-validate`, `sync-ids`, `feature-tracker-sync`	enabled	Read-leaning workflows that genuinely add value across 16 ADRs / 2 PRDs / 5 PRPs
`derive-prd`, `derive-plans`, `derive-rules`, `generate-rules`, `claude-md`, `curate-docs`	disabled	Would treat plugin source as project requirements or could overwrite the 18 hand-written rules / hand-curated `CLAUDE.md`

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.

Commit-scope convention for blueprint work

Scope	Effect	Use for
`chore(blueprint): …`	No version bump	Manifest bookkeeping, sync runs, ID assignments inside `docs/blueprint/`
`feat(blueprint-plugin): …`	Minor version bump on the published plugin	Skill changes inside `blueprint-plugin/`
`fix(blueprint-plugin): …`	Patch version bump	Bug fixes inside `blueprint-plugin/`

The blueprint scope (no -plugin suffix) intentionally does not match any release-please package, so dogfooding maintenance never accidentally publishes the plugin.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

claude-plugins

Project Structure

Rules

Creating New Skills

Quick Start

Skill Granularity Decision

Creating User-Invocable Skills

Agentic Optimization

Plugin Organization

Plugin Lifecycle

Files to Update

Creating a New Plugin

Deleting a Plugin

Git Workflow

Conventional Commits

Example Workflow

Development Workflow

Blueprint (constrained dogfooding)

Commit-scope convention for blueprint work

Conventions

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

claude-plugins

Project Structure

Rules

Creating New Skills

Quick Start

Skill Granularity Decision

Creating User-Invocable Skills

Agentic Optimization

Plugin Organization

Plugin Lifecycle

Files to Update

Creating a New Plugin

Deleting a Plugin

Git Workflow

Conventional Commits

Example Workflow

Development Workflow

Blueprint (constrained dogfooding)

Commit-scope convention for blueprint work

Conventions