Commands, Agents, and Skills in Claude Plugins: The Three-Layer Architecture

Commands are user-invoked slash commands for immediate actions, agents are specialized sub-agents that handle multi-step workflows, and skills are context-aware modules that Claude automatically activates when their descriptions match user intent.

The anthropics/claude-plugins-official repository defines a three-layer extension architecture for Claude Code. Understanding the distinction between these components is essential for building plugins that range from simple utilities to complex domain-specific automation.

Commands: Direct User Invocation

Commands implement slash commands that users trigger explicitly by typing /<command-name>. They provide immediate, single-purpose utilities within the Claude interface.

File Structure and Auto-Discovery

Commands reside in the commands/ directory at the plugin root. Claude automatically discovers any .md file in this folder during plugin initialization, registering the name and description from the front-matter as executable slash commands.

According to the plugin structure guide in plugins/plugin-dev/skills/plugin-structure/SKILL.md, all .md files in commands/ are auto-discovered without additional configuration【L10-L15】.

Front-Matter Configuration

Each command file requires YAML front-matter defining:

• name: The slash command identifier (e.g., run-tests)
• description: Help text displayed to users
• argument-hint: Optional parameter placeholder (e.g., <filename>)
• allowed-tools: Array of permitted tool operations (e.g., ["Read", "Bash"])

Command Example

Create commands/hello.md:

---
name: hello
description: Greet the user with a customizable message
argument-hint: <name>
allowed-tools: [Read]
---

# Hello Command

When run, this command replies with:

Hello, $ARGUMENTS!

When a user types /hello World, Claude executes the command body with access to the Read tool and substitutes $ARGUMENTS with "World".

Agents: Specialized Sub-Agents

Agents are expert sub-agents that Claude spawns to handle complex, multi-step analyses or domain-specific tasks. Unlike commands, agents run as separate Claude sessions with specialized instructions and potentially different model configurations.

Agent Configuration and Discovery

Agents live in the agents/ directory as individual .md files. As documented in plugins/plugin-dev/skills/plugin-structure/SKILL.md, Claude scans agents/ for all .md files and makes them available when higher-level capabilities are required【L36-L40】.

Front-matter for agents includes:

• name: Unique agent identifier
• description: When Claude should invoke this agent
• model: Optional model override (e.g., opus)
• color: Visual identifier for agent output

Agent Example

Create agents/code-simplifier.md:

---
name: code-simplifier
description: Refactor recent code changes to improve readability while preserving functionality.
model: opus
color: blue
---
You are an expert code simplifier. Analyze the latest git diff, propose a cleaned-up version, and explain each change.

When Claude determines that code simplification is needed—perhaps after a /review command—it loads this agent definition from agents/code-simplifier.md and spawns a new session with these specific instructions. The agent returns its analysis to the parent session.

Skills: Auto-Triggered Knowledge Artifacts

Skills are re-usable automation modules that Claude activates automatically when user input matches the skill's description. They represent the highest level of abstraction, enabling background automation without explicit command invocation.

Directory Structure Requirements

Skills require a specific nested structure: skills/<skill-name>/SKILL.md. The SKILL.md file serves as the manifest and instruction set. As defined in plugins/plugin-dev/skills/plugin-structure/SKILL.md, Claude scans skills/ for subdirectories containing a SKILL.md file to discover available capabilities【L64-L68】.

Skills support additional supporting files (templates, reference documents) within their subdirectory, making them self-contained packages of domain expertise.

Skill Example

Create skills/markdown-improver/SKILL.md:

---
name: markdown-improver
description: Improve the quality, style, and structure of a Markdown document.
version: 1.0.0
---
**Goal**: Take a raw `.md` file, rewrite it following best-practice guidelines (headings, lists, link formatting).

### Steps

1. Read the input file.
2. Apply style rules (see `references/style-guide.md`).
3. Write the improved file back to `${CLAUDE_PLUGIN_ROOT}/output.md`.

When a user mentions "improve this markdown file" or similar intent, Claude matches the description against this skill and executes its defined workflow automatically.

Execution Flow Comparison

Understanding how Claude processes each component clarifies their distinct roles:

• Commands: User types /<name> → Claude reads the .md file from commands/ → Validates arguments against argument-hint → Executes with allowed-tools permissions → Returns immediate result.

• Agents: Claude identifies need for expertise → Loads agent definition from agents/ → Spawns sub-session with agent instructions and optional model setting → Returns analysis to main conversation.

• Skills: Claude matches free-form text against skill descriptions in skills/*/SKILL.md → Activates matching skill workflow → May invoke internal agents or scripts → Returns automated result without explicit command.

Key Implementation Files

For reference implementations, examine these canonical examples in the anthropics/claude-plugins-official repository:

• Command structure: plugins/example-plugin/commands/example-command.md demonstrates complete front-matter and body composition【L1-L30】.

• Agent definition: plugins/pr-review-toolkit/agents/code-reviewer.md shows agent metadata and detailed instruction formatting【L1-L8】.

• Skill manifest: plugins/skill-creator/skills/skill-creator/SKILL.md illustrates versioning, purpose definition, and workflow instructions【L1-L8】.

Summary

• Commands live in commands/, provide immediate slash-command utilities, and require explicit user invocation with specific allowed tools.

• Agents reside in agents/, act as specialized sub-agents for multi-step analysis, and are spawned by Claude when domain expertise is required.

• Skills occupy skills/<name>/ directories with mandatory SKILL.md manifests, enable automatic context-aware automation, and trigger based on description matching without explicit commands.

• All three components use front-matter metadata and are auto-discovered during plugin initialization according to the structure defined in plugins/plugin-dev/skills/plugin-structure/SKILL.md.

Frequently Asked Questions

How does Claude decide when to use a skill versus a command?

Claude activates skills automatically when your natural language input semantically matches the skill's description field. In contrast, commands require you to type the exact /<command-name> syntax. Skills handle implicit intent detection, while commands provide explicit, precise control.

Can an agent call a command or another agent?

Yes. Agents operate as independent Claude sessions with access to the plugin's available tools and components. An agent can invoke commands through tool calls or spawn additional agents for sub-tasks. However, skills typically represent the highest-level automation and may internally orchestrate both agents and commands as part of their workflow.

What is the difference between allowed-tools in commands and agent capabilities?

Commands explicitly declare their tool permissions in the allowed-tools front-matter array (e.g., ["Read", "Bash"]), creating a restricted execution environment. Agents do not use allowed-tools; instead, they inherit standard Claude capabilities plus any tools available to the parent session, operating with broader autonomy appropriate for complex analysis tasks.

Where should I place configuration files for complex skills with multiple assets?

Place all skill-related files within the skills/<skill-name>/ subdirectory alongside the mandatory SKILL.md file. The skill can reference supporting documents (templates, schemas, or data files) using relative paths from ${CLAUDE_PLUGIN_ROOT}. This encapsulation keeps skills portable and self-contained, as demonstrated by the skill-creator skill structure in the official repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}