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

> Understand Claude plugins: commands for direct actions, agents for multi-step tasks, and skills for context-aware automation. Learn the three-layer architecture for enhanced functionality.

- Repository: [Anthropic/claude-plugins-official](https://github.com/anthropics/claude-plugins-official)
- Tags: architecture
- Published: 2026-03-13

---

**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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/commands/hello.md):

```markdown
---
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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/agents/code-simplifier.md):

```markdown
---
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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/SKILL.md) file serves as the manifest and instruction set. As defined in [`plugins/plugin-dev/skills/plugin-structure/SKILL.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/plugin-structure/SKILL.md), Claude scans `skills/` for subdirectories containing a [`SKILL.md`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/skills/markdown-improver/SKILL.md):

```markdown
---
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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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`](https://github.com/anthropics/claude-plugins-official/blob/main/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.