CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the comprehensive marketplace and learning hub for Claude Code plugins. It serves as both a distribution platform for plugins and an educational resource for plugin developers.

Repository Stats:

236 marketplace plugins across 15 categories
221 AI instruction plugins (markdown-based templates)
5 MCP server plugins (TypeScript/Node.js executables with 21 tools)
164 plugins with Agent Skills (v1.1.0)
Live marketplace at https://claudecodeplugins.io/
Monorepo using pnpm workspaces

Critical Architecture Understanding

Two Catalog System

This repository maintains two separate catalog files:

.claude-plugin/marketplace.extended.json (SOURCE OF TRUTH)
- Full metadata including featured, mcpTools, pricing, components
- Used by the Astro marketplace website
- Edit this file when adding/updating plugins
.claude-plugin/marketplace.json (GENERATED FILE)
- Sanitized version for Claude CLI compatibility
- Auto-generated by pnpm run sync-marketplace
- Contains only CLI-supported fields (strips extended metadata)
- NEVER edit this file directly

Catalog Sync Workflow

# After editing marketplace.extended.json:
pnpm run sync-marketplace  # Regenerates marketplace.json

# CI will fail if marketplace.json is out of sync
# Always run sync-marketplace before committing

The sync script (scripts/sync-marketplace.cjs) strips these fields: featured, mcpTools, pluginCount, pricing, components

Monorepo Structure

This is a pnpm workspace with two separate package ecosystems:

claude-code-plugins/
├── plugins/
│   ├── mcp/                       # MCP plugins (TypeScript/Node.js)
│   │   ├── project-health-auditor/    # 4 MCP tools
│   │   ├── conversational-api-debugger/ # 4 MCP tools
│   │   ├── domain-memory-agent/       # 6 MCP tools
│   │   ├── design-to-code/            # 3 MCP tools
│   │   └── workflow-orchestrator/     # 4 MCP tools
│   ├── examples/                  # Example/featured plugins
│   ├── packages/                  # Plugin packs
│   ├── community/                 # Community-contributed plugins
│   ├── skill-enhancers/          # Skill automation plugins
│   └── fairdb-operations-kit/    # Production database operations
│       ├── agents/                # Database health, emergency response
│       ├── commands/              # Setup, onboarding workflows
│       └── skills/                # Automated database management
├── marketplace/                   # Astro website (Node.js)
│   ├── src/                      # Astro 5.14.5 + Tailwind 4
│   └── dist/                     # Built site → GitHub Pages
├── scripts/                      # Build and validation scripts
├── .github/workflows/            # CI/CD automation
└── pnpm-workspace.yaml           # Workspace config

Common Development Commands

Catalog Management

# After editing marketplace.extended.json (ALWAYS RUN THIS):
pnpm run sync-marketplace

# Validate catalogs are in sync (CI check):
node scripts/sync-marketplace.cjs
git diff --quiet .claude-plugin/marketplace.json  # Should show no changes

Validation & Testing

# Comprehensive validation (run before committing):
./scripts/validate-all.sh

# Validate specific plugin/directory:
./scripts/validate-all.sh plugins/mcp/project-health-auditor/

# Test plugin installation locally:
./scripts/test-installation.sh

# Check markdown frontmatter:
python3 scripts/check-frontmatter.py

# Validate specific JSON file:
jq empty path/to/file.json

MCP Plugin Development

# Install dependencies for all MCP plugins:
pnpm install

# Build all MCP plugins:
pnpm build

# Build specific MCP plugin:
cd plugins/mcp/[plugin-name]/
pnpm build

# Run tests:
pnpm test  # All plugins
cd plugins/mcp/[plugin-name]/ && pnpm test  # Specific plugin

# Type checking:
pnpm typecheck

# Lint code:
pnpm lint

# Development mode (watch mode):
pnpm dev

Marketplace Website Development

cd marketplace/

# Development server (http://localhost:4321):
npm run dev

# Production build:
npm run build

# Preview production build:
npm run preview

# Generate missing plugin pages:
node generate-missing-plugins.cjs

# Generate plugin content:
node generate-content.js

Agent Skills Generation (v1.1.0+)

# Generate skills for next plugin in queue:
./scripts/next-skill.sh

# Generate skills using Gemini API (batch mode):
python3 scripts/generate-skills-gemini.py

# Generate skills using Vertex AI (safe mode with backups):
python3 scripts/vertex-skills-generator-safe.py

# Fix plugin manifests (remove invalid fields):
./scripts/fix-manifests.sh

FairDB Operations (Production Database Plugin)

# Health check for PostgreSQL infrastructure:
/fairdb-operations-kit:fairdb-health-check

# Emergency incident response:
/fairdb-operations-kit:fairdb-emergency-response

# Configure pgBackRest with Wasabi S3 backups:
/fairdb-operations-kit:fairdb-setup-backup

# Complete customer onboarding workflow:
/fairdb-operations-kit:fairdb-onboard-customer

Local Plugin Testing Workflow

# 1. Create test marketplace structure:
mkdir -p ~/test-marketplace/.claude-plugin

# 2. Create marketplace.json pointing to local plugin:
cat > ~/test-marketplace/.claude-plugin/marketplace.json << 'EOF'
{
  "name": "test",
  "owner": {"name": "Test"},
  "plugins": [{
    "name": "my-plugin",
    "source": "/absolute/path/to/plugins/community/my-plugin"
  }]
}
EOF

# 3. Add test marketplace to Claude Code:
/plugin marketplace add ~/test-marketplace

# 4. Install and test:
/plugin install my-plugin@test
/my-command  # Test slash commands

Adding a New Plugin

Complete Workflow

Create plugin structure:

mkdir -p plugins/community/your-plugin/.claude-plugin
mkdir -p plugins/community/your-plugin/commands  # If using commands
mkdir -p plugins/community/your-plugin/agents    # If using agents
mkdir -p plugins/community/your-plugin/skills/skill-adapter  # For Agent Skills

Create required files:
- .claude-plugin/plugin.json (metadata with name, version, description, author)
- README.md (comprehensive documentation with examples)
- LICENSE (MIT or Apache-2.0 recommended)
- At least one component directory
Update marketplace.extended.json (SOURCE):

{
  "plugins": [
    {
      "name": "your-plugin",
      "source": "./plugins/community/your-plugin",
      "description": "Clear one-line description",
      "version": "1.0.0",
      "category": "productivity",
      "keywords": ["keyword1", "keyword2"],
      "author": {
        "name": "Your Name",
        "email": "your.email@example.com"
      }
    }
  ]
}

Regenerate CLI catalog:

pnpm run sync-marketplace

Validate:

./scripts/validate-all.sh plugins/community/your-plugin/
jq '.plugins[] | select(.name == "your-plugin")' .claude-plugin/marketplace.json

Test locally using the test marketplace workflow above
Submit PR using .github/PULL_REQUEST_TEMPLATE.md

Plugin Architecture Details

AI Instruction Plugins (221 plugins)

Markdown files with YAML frontmatter
Work through Claude's interpretation
No external code execution
Categories: api-development, ai-ml, security, devops, crypto, database, testing, performance, productivity, ai-agency

Required frontmatter for commands/agents:

---
name: command-name
description: What this does
model: sonnet  # or haiku
---

Important: As of v1.0.46, the opus model identifier has been deprecated. Use sonnet for production plugins requiring advanced reasoning, or haiku for simple tasks.

MCP Server Plugins (5 plugins)

TypeScript/Node.js applications
Run as separate processes
Build with @modelcontextprotocol/sdk
Compiled to JavaScript in dist/
Each provides 3-6 MCP tools

MCP plugin structure:

plugin-name/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (gitignored)
├── package.json          # Node.js dependencies
├── tsconfig.json         # TypeScript config
└── .claude-plugin/
    ├── plugin.json       # Plugin metadata
    └── mcp/
        └── server.json   # MCP server configuration

Agent Skills (v1.1.0+)

Model-invoked capabilities that activate automatically
Claude decides when to use based on conversation context
Placed in skills/skill-adapter/SKILL.md
Contains trigger phrases and workflow instructions

Agent Skills structure:

plugin-name/
└── skills/
    └── skill-adapter/
        └── SKILL.md      # Agent skill definition

SKILL.md frontmatter:

---
name: Skill Name
description: |
  What this skill does and when to use it.
  Include trigger phrases for automatic activation.
---

Critical Conventions

Path Variables

Always use ${CLAUDE_PLUGIN_ROOT} in hooks for portable paths:

{
  "hooks": {
    "PostToolUse": {
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
    }
  }
}

Script Permissions

All shell scripts MUST be executable (validated by CI):

chmod +x scripts/*.sh
find . -type f -name "*.sh" -exec chmod +x {} \;

Plugin Categories

Valid categories: productivity, security, testing, deployment, documentation, analysis, integration, ai, devops, debugging, code-quality, design, example, api-development, database, crypto, performance, ai-ml, skill-enhancers, other

Versioning

Follow semantic versioning (MAJOR.MINOR.PATCH):

1.0.0 - Initial release
1.1.0 - New feature, backward compatible
1.1.1 - Bug fix
2.0.0 - Breaking change

Version must be updated in:

VERSION file (root)
package.json (root)
marketplace.extended.json (metadata.version)
Individual plugin plugin.json files (when updating plugins)

CI/CD Pipeline

GitHub Actions Workflows

.github/workflows/validate-plugins.yml (runs on PR and main push)
- Validates marketplace.json is in sync with marketplace.extended.json
- Checks JSON syntax with jq
- Validates plugin structure (plugin.json, README.md, LICENSE)
- Verifies script permissions (chmod +x)
- Security scans:
  - Hardcoded secrets detection
  - AWS keys detection (blocks CI)
  - Private key detection (blocks CI)
  - Dangerous command patterns (rm -rf /)
  - Command injection risks (eval())
  - Suspicious URLs (non-HTTPS, URL shorteners)
- MCP plugin dependency audit (npm audit)
.github/workflows/deploy-marketplace.yml (deploys to GitHub Pages)
- Builds Astro site (cd marketplace && npm run build)
- Deploys to https://claudecodeplugins.io/
.github/workflows/release.yml (version tagging)
- Creates GitHub releases with changelog
- Semantic versioning tags
.github/workflows/daily-skill-generator.yml (scheduled)
- Automated Agent Skills generation using Vertex AI
- Runs daily to process plugin queue
- Creates database backups before generation
.github/workflows/security-audit.yml (security scanning)
- CodeQL analysis
- Dependency vulnerability scanning
.github/workflows/automerge.yml (automated PR merging)
- Auto-merges dependabot PRs after CI passes
- Reduces maintenance overhead for dependency updates
.github/workflows/maintainer-ready-automerge.yml (maintainer workflow)
- Auto-merges PRs labeled "maintainer-ready"
- Requires all CI checks to pass
- Streamlines approved PR merging

Pre-commit Checklist

Before committing changes:

# 1. Sync catalogs if you edited marketplace.extended.json:
pnpm run sync-marketplace

# 2. Run full validation:
./scripts/validate-all.sh

# 3. Make scripts executable:
find . -type f -name "*.sh" -exec chmod +x {} \;

# 4. Validate JSON:
find . -name "*.json" -exec sh -c 'jq empty {}' \;

# 5. Check for secrets:
grep -r "password\|secret\|api_key" plugins/ | grep -v placeholder

# 6. Update version numbers if needed:
# - VERSION file
# - package.json
# - marketplace.extended.json (metadata.version)

# 7. Verify model identifiers (no 'opus'):
grep -r "model: opus" plugins/ commands/ agents/
# Should return empty - replace with 'sonnet' if found

Common Issues & Troubleshooting

Marketplace Sync Failures

Error: CI fails with "Marketplace CLI catalog was out of date"

Solution:

pnpm run sync-marketplace
git add .claude-plugin/marketplace.json
git commit --amend --no-edit

Plugin Not Appearing

Checklist:

Valid plugin.json with required fields (name, version, description, author)
Entry exists in marketplace.extended.json
Ran pnpm run sync-marketplace after adding entry
Plugin source path is correct relative to repo root
At least one component directory exists (commands/, agents/, hooks/, mcp/, skills/, or scripts/)

Scripts Not Executing

Common causes:

Missing execute permission → chmod +x script.sh
Wrong shebang → Should be #!/bin/bash or #!/usr/bin/env bash
Absolute path in hooks → Use ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh

Hooks Not Firing

Debugging steps:

Validate hooks.json syntax with jq
Check matcher patterns match your use case
Verify script path uses ${CLAUDE_PLUGIN_ROOT}
Test hook script independently

MCP Plugin Build Failures

Common issues:

Missing dependencies → pnpm install
TypeScript errors → pnpm typecheck
Wrong Node version → Use Node.js 20+
Missing @modelcontextprotocol/sdk → Check package.json

Agent Skills Generation Issues

Common issues:

API key not configured → Set GOOGLE_APPLICATION_CREDENTIALS or Vertex AI credentials
Database locked → Wait for current generation to complete
Quota exceeded → Vertex AI has rate limits
Invalid plugin structure → Ensure plugin has proper README.md and plugin.json

Recovery:

# Check generation status:
cat backups/skills_generation.db | sqlite3

# Restart from backup:
cp backups/skills_generation.db.backup backups/skills_generation.db

# Process next plugin manually:
./scripts/next-skill.sh

Invalid Model Identifier Errors

Error: Plugin fails with "Invalid model: opus"

Solution: The opus model identifier was deprecated in v1.0.46. Update your plugin frontmatter:

# Find all instances:
grep -r "model: opus" plugins/

# Replace with:
model: sonnet  # For advanced reasoning tasks
# or
model: haiku   # For simple, fast tasks

After updating, validate and sync:

./scripts/validate-all.sh
pnpm run sync-marketplace

Security Requirements

Never hardcode secrets - Use environment variables or user prompts
Validate all inputs in scripts before executing commands
Use ${CLAUDE_PLUGIN_ROOT} for all paths in hooks
Request minimal permissions - Don't ask for system-wide access
No destructive operations without explicit user confirmation
All .sh files must be executable - Enforced by CI
No private keys or AWS keys - Blocks CI immediately
Agent Skills security - Never include API keys or credentials in SKILL.md files

File Structure Requirements

Required Files (Every Plugin)

plugin-name/
├── .claude-plugin/
│   └── plugin.json              # REQUIRED: name, version, description, author
├── README.md                     # REQUIRED: Documentation with examples
├── LICENSE                       # REQUIRED: MIT or Apache-2.0 recommended
└── [commands|agents|hooks|mcp|scripts|skills]/  # At least one component

plugin.json Schema

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Clear description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com"
  },
  "repository": "https://github.com/username/repo",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

Command/Agent Markdown Format

---
name: command-name
description: Brief description
model: sonnet
---

# Command Title

Detailed instructions for Claude...

Agent Skills Markdown Format

---
name: Skill Name
description: |
  Brief description of what this skill does.
  Include trigger phrases that activate this skill.
---

## How It Works
Step-by-step explanation of the skill workflow

## When to Use This Skill
- Trigger phrase 1
- Trigger phrase 2
- Use case descriptions

## Examples
User: "trigger phrase"
Skill activates → performs action → result

Hooks Format

{
  "hooks": {
    "PostToolUse": {
      "matchers": [
        {
          "tools": ["Edit", "Write"],
          "filePatterns": ["**/*.py"]
        }
      ],
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
    }
  }
}

Package Management

pnpm Workspace Commands

# Install dependencies for all workspace packages:
pnpm install

# Run script in all packages:
pnpm --filter '*' build
pnpm --filter '*' test

# Run script in specific package:
pnpm --filter project-health-auditor build

# Add dependency to specific package:
cd plugins/mcp/plugin-name/
pnpm add dependency-name

# Update all dependencies:
pnpm update -r

# Clean all node_modules:
pnpm --filter '*' clean

Marketplace Distribution

Installation Commands

Users install plugins from this marketplace:

# Add marketplace (GitHub shorthand):
/plugin marketplace add jeremylongshore/claude-code-plugins

# Install plugins:
/plugin install plugin-name@claude-code-plugins-plus
/plugin install devops-automation-pack@claude-code-plugins-plus
/plugin install project-health-auditor@claude-code-plugins-plus

Marketplace Slug

Marketplace name: claude-code-plugins-plus
GitHub repo: jeremylongshore/claude-code-plugins
Live site: https://claudecodeplugins.io/

Important Context

NOT GitHub Marketplace

Claude Code plugins use their own ecosystem with JSON-based marketplace catalogs. This repository IS a Claude Code plugin marketplace, not related to GitHub's marketplace for Actions/Apps.

No Built-in Monetization

There is no monetization mechanism for Claude Code plugins. All plugins are free and open-source. External revenue strategies exist (consulting, support, premium versions).

Beta Status (October 2025)

Claude Code plugins are in public beta. Features and best practices evolve. This marketplace stays updated with latest changes.

Three Plugin Types Coexist

AI Instruction Plugins: Guide Claude's behavior through markdown templates (221 plugins)
MCP Server Plugins: Execute TypeScript/Node.js code in separate processes (5 plugins)
Agent Skills: Model-invoked capabilities that activate automatically (164 plugins equipped)

All three types are valid and fully functional approaches. Plugins can bundle Skills, Commands, Agents, and MCP servers together.

Resources

Official Documentation

Claude Code Docs: https://docs.claude.com/en/docs/claude-code/
Plugin Guide: https://docs.claude.com/en/docs/claude-code/plugins
Plugin Reference: https://docs.claude.com/en/docs/claude-code/plugins-reference

Community

Discord: https://discord.com/invite/6PPFFzqPDZ (#claude-code channel)
GitHub Issues: https://github.com/jeremylongshore/claude-code-plugins/issues
GitHub Discussions: https://github.com/jeremylongshore/claude-code-plugins/discussions

This Repository

CONTRIBUTING.md - Submission guidelines
SECURITY.md - Security policy and threat model
CODE_OF_CONDUCT.md - Community standards
USER_SECURITY_GUIDE.md - Safe plugin evaluation
MCP-SERVERS-STATUS.md - MCP plugin configurations
CHANGELOG.md - Version history
SETUP.md - Development environment setup
scripts/PRODUCTION_SAFETY_GUIDE.md - Production deployment guidelines
scripts/SKILLS_AUTOMATION.md - Agent Skills generation documentation

Development Principles

When working in this repository:

Always sync catalogs: Run pnpm run sync-marketplace after editing marketplace.extended.json
Validate before committing: Run ./scripts/validate-all.sh
Test locally first: Use test marketplace pattern to verify plugins work
Executable scripts: All .sh files need chmod +x (CI enforced)
JSON validation: Use jq empty file.json to validate syntax
Frontmatter required: All command/agent/skill markdown files need YAML frontmatter
Portable paths: Always use ${CLAUDE_PLUGIN_ROOT} in hooks
Documentation first: Every plugin needs comprehensive README.md
Security conscious: No hardcoded secrets, validate inputs, minimal permissions
Two-catalog awareness: Edit .extended.json (source), generate .json (CLI)
Version consistency: Update VERSION, package.json, and marketplace.extended.json together
Agent Skills best practices: Include trigger phrases in descriptions, follow SKILL.md format

Key Workflows

Adding a Plugin with Agent Skills

# 1. Create plugin structure
mkdir -p plugins/community/my-plugin/.claude-plugin
mkdir -p plugins/community/my-plugin/commands
mkdir -p plugins/community/my-plugin/skills/skill-adapter

# 2. Create plugin.json, README.md, LICENSE, commands/

# 3. Generate Agent Skill
./scripts/next-skill.sh  # Interactive skill generation

# 4. Update marketplace
# Edit .claude-plugin/marketplace.extended.json
pnpm run sync-marketplace

# 5. Validate
./scripts/validate-all.sh plugins/community/my-plugin/

# 6. Test locally
# Use test marketplace workflow

# 7. Commit and PR
git add .
git commit -m "feat: add my-plugin with Agent Skills"

Deploying Website Updates

# 1. Build marketplace website
cd marketplace/
npm run build

# 2. Test locally
npm run preview

# 3. Commit changes
git add dist/
git commit -m "build: update marketplace website"

# 4. Push to main (auto-deploys via GitHub Actions)
git push origin main

# 5. Verify deployment at https://claudecodeplugins.io/

Creating a Release

# 1. Update version numbers
echo "1.1.1" > VERSION
# Edit package.json version field
# Edit marketplace.extended.json metadata.version

# 2. Update CHANGELOG.md
# Add release notes for version 1.1.1

# 3. Sync marketplace
pnpm run sync-marketplace

# 4. Validate everything
./scripts/validate-all.sh

# 5. Commit version bump
git add VERSION package.json .claude-plugin/marketplace.extended.json .claude-plugin/marketplace.json CHANGELOG.md
git commit -m "chore: bump version to 1.1.1"

# 6. Create tag
git tag -a v1.1.1 -m "Release v1.1.1"

# 7. Push with tags
git push origin main --tags

# 8. GitHub Actions will create the release automatically

Documentation Filing System

This repository uses a structured documentation filing system for all internal project documentation.

Documentation Structure

claude-code-plugins/
└── 000-docs/           # All project documentation (FLAT - no subdirectories)
    ├── 001-XX-XXXX-description.md
    ├── 002-XX-XXXX-description.md
    └── ...

File Naming Standard

Format: NNN-CC-ABCD-short-description.ext

NNN = Zero-padded sequence (001-999) for chronological ordering
CC = Two-letter category code (see below)
ABCD = Four-letter document type abbreviation
short-description = 1-4 words, kebab-case, lowercase
ext = File extension (.md, .pdf, .txt, etc.)

Category Codes (2-letter)

Code	Category	Examples
PP	Product & Planning	Requirements, roadmaps, business planning
AT	Architecture & Technical	Technical decisions, system design
DC	Development & Code	Code documentation, modules
TQ	Testing & Quality	Test plans, QA, bug reports
OD	Operations & Deployment	DevOps, deployment guides
LS	Logs & Status	Status logs, progress tracking
RA	Reports & Analysis	Reports, analytics, research
MC	Meetings & Communication	Meeting notes, memos
PM	Project Management	Tasks, sprints, risks
DR	Documentation & Reference	Guides, manuals, SOPs
UC	User & Customer	User docs, training
BL	Business & Legal	Contracts, compliance
RL	Research & Learning	Research, experiments, POCs
AA	After Action & Review	Post-mortems, retrospectives
MS	Miscellaneous	General, drafts, archives

Document Type Abbreviations (4-letter)

Common examples:

PROD = Product Requirements Document
ADEC = Architecture Decision Record
GUID = User Guide/Documentation
TEST = Test Plan/Strategy
REFF = Reference Material/Guide
TASK = Task Documentation
MEET = Meeting Notes/Minutes
SUMM = Summary/Executive Summary
REPT = General Report
SOPS = Standard Operating Procedure
CHKL = Checklist
RELS = Release Notes

Full specification: See 000-docs/000-DR-REFF-filing-system-standard-v2.md

Examples

001-AT-ADEC-initial-architecture.md          # Architecture decision
002-PP-PROD-core-features.md                 # Product requirements
003-MC-MEET-kickoff-notes.md                 # Meeting notes
048-RA-INDX-audit-index.md                   # Audit index
075-OD-RELS-changelog-v1-2-0.md             # Release notes
086-PP-PLAN-release-v1-2-0.md               # Release plan

Rules

FLAT structure - 000-docs/ contains NO subdirectories
Chronological order - Sequence numbers enforce creation order
Standard files stay in root - README.md, CHANGELOG.md, CLAUDE.md, etc. remain at project root
All internal docs go to 000-docs/ - Work logs, reports, guides, meeting notes, etc.

Last Updated: October 28, 2025 Repository Version: 1.2.5 (236 plugins, 171 with Agent Skills) Status: Active, accepting community contributions Recent Changes: v1.2.0 Agent Skills Quality Enhancement, documentation reorganization, 000-docs/ filing system implemented

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md

Repository Overview

Critical Architecture Understanding

Two Catalog System

Catalog Sync Workflow

Monorepo Structure

Common Development Commands

Catalog Management

Validation & Testing

MCP Plugin Development

Marketplace Website Development

Agent Skills Generation (v1.1.0+)

FairDB Operations (Production Database Plugin)

Local Plugin Testing Workflow

Adding a New Plugin

Complete Workflow

Plugin Architecture Details

AI Instruction Plugins (221 plugins)

MCP Server Plugins (5 plugins)

Agent Skills (v1.1.0+)

Critical Conventions

Path Variables

Script Permissions

Plugin Categories

Versioning

CI/CD Pipeline

GitHub Actions Workflows

Pre-commit Checklist

Common Issues & Troubleshooting

Marketplace Sync Failures

Plugin Not Appearing

Scripts Not Executing

Hooks Not Firing

MCP Plugin Build Failures

Agent Skills Generation Issues

Invalid Model Identifier Errors

Security Requirements

File Structure Requirements

Required Files (Every Plugin)

plugin.json Schema

Command/Agent Markdown Format

Agent Skills Markdown Format

Hooks Format

Package Management

pnpm Workspace Commands

Marketplace Distribution

Installation Commands

Marketplace Slug

Important Context

NOT GitHub Marketplace

No Built-in Monetization

Beta Status (October 2025)

Three Plugin Types Coexist

Resources

Official Documentation

Community

This Repository

Development Principles

Key Workflows

Adding a Plugin with Agent Skills

Deploying Website Updates

Creating a Release

Documentation Filing System

Documentation Structure

File Naming Standard

Category Codes (2-letter)

Document Type Abbreviations (4-letter)

Examples

Rules