Plugin Structure

Plugin Structure

Every plugin in the claude-code-plugins-plus-skills repository lives under plugins/[category]/[plugin-name]/. There are two types of plugins: AI instruction plugins (Markdown-based, ~98% of the catalog) and MCP server plugins (TypeScript-based, ~2%).

---

AI Instruction Plugins

The majority of plugins are pure Markdown. They provide slash commands, agents, and auto-activating skills that load as context into the LLM.

plugins/[category]/[plugin-name]/
├── .claude-plugin/plugin.json    # Required — plugin metadata
├── README.md                     # Required — human-readable documentation
├── commands/*.md                 # Slash commands (YAML frontmatter)
├── agents/*.md                   # Custom agents (YAML frontmatter)
└── skills/[skill-name]/SKILL.md  # Auto-activating skills

Key Directories

• commands/ -- Each .md file becomes an invocable slash command. The file uses YAML frontmatter to declare metadata and the body contains the instructions Claude follows.
• agents/ -- Custom agent definitions. Same frontmatter convention as commands.
• skills/[skill-name]/ -- Each skill lives in its own directory. The SKILL.md file is the only required file; supporting resources go in scripts/, references/, templates/, or assets/ subdirectories. See the SKILL.md Specification for the full standard.

---

MCP Server Plugins

MCP (Model Context Protocol) plugins are TypeScript server implementations that expose tools to Claude. See MCP Server Plugins for a detailed guide.

plugins/mcp/[plugin-name]/
├── .claude-plugin/plugin.json    # Required — plugin metadata
├── src/*.ts                      # TypeScript source files
├── dist/index.js                 # Built entry point (must be executable)
├── package.json                  # Node.js dependencies
└── .mcp.json                     # MCP server configuration

The dist/index.js file must include a Node.js shebang (#!/usr/bin/env node) and be marked executable (chmod +x).

---

plugin.json

Every plugin requires a .claude-plugin/plugin.json file. CI enforces that only the following fields are present:

Field	Required	Description
name	Yes	Plugin name (kebab-case)
version	Yes	Semver version string
description	Yes	What the plugin does
author	Yes	Author name or Name <email>
repository	No	GitHub repository URL
homepage	No	Plugin homepage URL
license	No	SPDX license identifier
keywords	No	Array of discovery keywords

Any fields not in this list cause a CI validation failure. This keeps plugin metadata predictable for the Two Catalog System and the ccpi CLI.

---

SaaS Skill Packs

SaaS skill packs bundle multiple related skills into a single installable unit. They live under plugins/saas-packs/ and follow the *-pack naming convention:

plugins/saas-packs/example-pack/
├── .claude-plugin/plugin.json
├── README.md
└── skills/
    ├── skill-one/SKILL.md
    ├── skill-two/SKILL.md
    └── skill-three/SKILL.md

Each pack is a pnpm workspace member, which means it participates in the monorepo dependency graph and can be versioned independently.

---

Templates

The repository includes starter templates to bootstrap new plugins:

Template	Use Case
minimal	Bare-bones plugin with just plugin.json and README.md
command	Plugin with a slash command
agent	Plugin with a custom agent
full	Complete plugin with commands, agents, and skills

See Templates and Examples for usage instructions.

---

Related Pages

• Frontmatter Reference -- YAML fields for SKILL.md files
• SKILL.md Specification -- The full skill standard
• Validation and Grading -- How plugins are validated in CI
• Repository Structure -- Top-level monorepo layout