Component Model

Plugins are built from three composable layers: Commands (user entry points), Skills (orchestration), and Agents (isolated workers). Each layer has a single responsibility and can be combined in flexible workflows.

The Three Layers

Commands

User-invoked entry points. Each command is a slash command like /specs:prd or /git:pr.

Characteristics:

• Receive user arguments from the command line
• Run immediately on invocation
• Can accept structured input (flags, positional args)
• Live in commands/ as markdown with description frontmatter

When to use: Surface-level actions with a single input. E.g., /git:pr creates a PR; /utils:save saves a scratchpad.

Format:

---
description: Brief description shown in /plugin help
---

# Command Name

Instructions for Claude on how to execute this command.

Skills

Orchestration layer that chains operations, spawns agents, and interacts with the user.

Characteristics:

• Receive input from commands or other skills
• Can launch agents in parallel via subagent_type
• Can chain to other skills using USE Skill tool
• Can pause and ask user for decisions (AskUserQuestion)
• Live in skills/<name>/ as SKILL.md with frontmatter
• The description frontmatter controls autonomous activation by Claude

When to use: Multi-step workflows, decision points, or when you need to spawn isolated workers. E.g., /specs:plan orchestrates exploration, research, and planning phases.

Format:

---
name: plan
description: >-
  Creates a 2-plan.md decision document. Use when 1-prd.md exists and
  the next pipeline step is architectural planning.
---

# Skill Name

Instructions for the skill. Can use Skill, Task, AskUserQuestion tools.

Agents

Isolated, parallel workers spawned by skills. No direct user interaction.

Characteristics:

• Run in isolation with a focused context
• Can run in parallel (multiple agents at once)
• Have no UI interaction — all decisions were made by the skill before spawning
• Can use any tool directly (Read, Bash, Write, etc.)
• Live in agents/ as markdown files with name and description frontmatter

When to use: Long-running work that can be parallelized or isolated. E.g., a skill spawns three researcher agents to explore different aspects in parallel, then synthesizes results.

Format:

---
name: researcher
description: When Claude should use this agent
model: sonnet
---

# Agent Name

Detailed instructions for the agent. Full tool access, no UI.

Invocation Patterns

Commands are the entry point: when you type /specs:prd, you invoke a command that runs a skill. Skills can then spawn multiple agents in parallel (via subagent_type), chain to other skills (via the USE Skill tool), or pause and ask you a question before continuing. Agents never spawn other agents — they execute work in isolation. This layering keeps concerns separate: commands handle user input, skills orchestrate logic and decision points, agents do the actual work.

Pattern	Usage
Command → Skill	User invokes /plugin:command which runs a skill
Skill → Agents	Skill spawns agents in parallel via subagent_type
Skill → Skill	Skill chains to another skill via USE Skill tool
AskUserQuestion	Skill pauses for user decision before continuing

Plugin Files

Manifest (.claude-plugin/plugin.json)

Declares what your plugin contains:

{
  "name": "specs",
  "version": "2.0.0",
  "description": "Spec-driven development: prd → plan → blueprint → build",
  "author": {
    "name": "Agronod",
    "email": "team@agronod.com"
  },
  "commands": ["./commands/"],
  "agents": ["./agents/"],
  "skills": ["./skills/"],
  "hooks": "./hooks/hooks.json"
}

Marketplace Registry (.claude-plugin/marketplace.json)

Lists all available plugins for discovery:

{
  "plugins": [
    {
      "name": "specs",
      "source": "./plugins/specs",
      "description": "Spec-driven development",
      "version": "2.0.0"
    }
  ]
}

Design Principles

• Separation of concerns: Each layer has one job — commands receive input, skills orchestrate, agents execute
• Parallelism: Skills spawn agents in parallel; results are collected when ready
• User checkpoints: Skills pause via AskUserQuestion to prevent costly misalignments
• Composability: Skills chain to other skills; agents are reusable; commands invoke skills

Creating Plugins

Refer to CONTRIBUTING.md in the claude-plugins repository for detailed plugin authoring guidelines, including:

• Plugin structure checklist
• How to write effective skill descriptions for autonomous activation
• Command, agent, and skill templates
• Best practices for error handling and user feedback

Related

• Specs Workflow — Example: the four-phase workflow (Commands → Skills → Agents)
• Skill Activation — How Claude discovers and uses skills autonomously
• Plugins Overview — Installation and marketplace overview