Agent-Skill-Command Interaction Model

Every plugin in the ecosystem is built from some combination of three building blocks: skills, commands, and agents. They look similar on the surface — they're all Markdown files with YAML frontmatter — but they behave in completely different ways at runtime. Understanding the difference isn't just academic. It changes how you design plugins, where bugs hide, and why some plugins feel effortless while others require constant coaxing.

This analysis is based on 315 plugins across the ecosystem, covering 1,372 skills, hundreds of commands, and 44 agent definitions. The numbers tell a clear story about which patterns developers actually reach for — and which they avoid.

Three Types, Three Jobs

The easiest way to understand skills, commands, and agents is by asking a single question about each: who decides when this runs?

For a skill, Claude decides. For a command, the user decides. For an agent, another piece of the system decides — either a skill or a command that delegates work it can't handle alone.

That one distinction explains most of the behavioral differences you'll observe in production. Skills are ambient — they're always potentially active, waiting for Claude to recognize a situation that matches their description. Commands are on-demand — they only fire when someone types the slash command explicitly. Agents are specialized — they exist to handle a narrow class of tasks with dedicated context and permissions.

None of these types is inherently better than the others. They're designed for different situations, and the most interesting plugins use two or three of them in combination. But before getting to composition, it helps to understand each type in isolation.

How Skills Get Activated

A skill's activation mechanism is its description field in the YAML frontmatter. That's it. There's no registration step, no function call, no explicit trigger. Claude reads the description and decides whether the current situation matches.

Here's what a typical skill's frontmatter looks like:

---
name: commit-message-writer
description: |
  Use this skill when writing or improving git commit messages.
  Triggered by: committing changes, reviewing staged files,
  drafting changelogs, or any request that involves summarizing
  what changed in a codebase and why.
allowed-tools: Read, Bash(git:*)
version: 1.0.0
author: Your Name <you@example.com>
---

The description does two jobs simultaneously: it tells Claude when to activate the skill, and it tells the plugin author what situations the skill handles. A well-written description reads like a set of trigger conditions. A poorly written one reads like a marketing blurb — and it activates erratically as a result.

The description field is the most important line in a SKILL.md file. Everything else — tool permissions, instructions, examples — only matters if Claude decides to load the skill in the first place. A skill with a vague description is a skill that activates unpredictably or not at all.

The allowed-tools field is the second critical element. It declares exactly which tools the skill can use when it runs. This isn't just a security constraint — it's a signal to Claude about the skill's capabilities. A skill with allowed-tools: Read is clearly for analysis. A skill with allowed-tools: Write, Edit, Bash is clearly for making changes.

The ecosystem's most common allowed-tools combinations reveal how plugin authors think about skill scope:

Skills are passive in the sense that they don't initiate anything. But once activated, they can be quite active — running commands, reading files, writing output. The "passive" label refers to activation, not capability.

How Commands Get Invoked

Commands are the opposite of skills in the most important way: the user is always in the loop. When someone types /commit or /review-pr, that's an explicit, intentional act. Nothing about the current context matters — the user has decided they want this specific behavior right now.

This explicitness is the entire point. Commands are for workflows where predictability matters more than automation. You don't want your code review process to trigger automatically based on vague context matching — you want to type /review-pr when you're ready to review, and have it work exactly as designed, every time.

Command files look structurally similar to SKILL.md files:

---
name: review-pr
description: Comprehensive pull request review with security and performance checks
allowed-tools: Read, Bash(git:*), Glob, Grep
---

## PR Review Process

1. Fetch the PR diff and changed files
2. Analyze for security issues, performance regressions, and style violations
3. Check test coverage for changed code
4. Generate a structured review comment

...

The frontmatter is nearly identical to a SKILL.md. The behavioral difference is entirely in how Claude Code handles the file — commands are registered as slash commands in the UI, while skills are loaded contextually. A user will see /review-pr in their command palette; they'll never see a skill name unless they go looking for it.

Over half the plugins in the ecosystem — 231 of 441, or 52.3% — include at least one command. This is the most common non-skill content type. Developers reach for commands when they have a workflow with a clear entry point that users should be able to invoke deliberately.

The most popular command categories across the ecosystem cluster around a few workflow types: git operations (commit, PR review, changelog), code quality (lint, format, test), documentation (generate docs, update README), and project management (status, standup, retrospective). These are all situations where a user wants to say "do this thing now" rather than "be ready to do this thing when relevant."

How Agents Get Delegated To

Agents are the rarest content type in the ecosystem by a significant margin. Only 44 plugins — about 10% — define agents. Understanding why requires understanding what agents are actually for.

An agent is a specialized worker with its own context, its own instructions, and often its own tool permissions. It gets called when a skill or command decides it needs focused expertise that's better handled in an isolated context. The key word is "isolated" — an agent gets a fresh context for its specific task, which means it's not contaminated by the broader conversation history.

Think of it this way: if a skill is a generalist who knows when to help, and a command is a workflow you invoke explicitly, an agent is a specialist you bring in for a particular part of the job. You wouldn't hire a specialist for every task — only for the ones where specialized context and focus are worth the overhead.

Agent definitions specify their own capabilities:

---
name: security-reviewer
description: Specialized agent for security analysis of code changes.
  Called when a PR review or code analysis identifies security-relevant
  patterns that require dedicated scrutiny.
allowed-tools: Read, Glob, Grep, WebFetch
model: sonnet
---

## Security Analysis Protocol

You are a security specialist. Your job is to analyze the provided
code for vulnerabilities, not to review style or architecture.

Focus exclusively on:
- Authentication and authorization flows
- Input validation and sanitization
- Secrets handling and exposure risks
- Dependency vulnerability patterns
...

Notice how the agent's instructions are narrow and focused. It's not trying to do a comprehensive code review — it's doing one specific thing well. That specialization is the entire justification for using an agent rather than just making the parent skill more capable.

Agents earn their complexity when two conditions hold: the subtask requires significantly different expertise from the parent workflow, and isolating that expertise in a fresh context produces meaningfully better results. If either condition is false, a well-scoped skill will serve you better.

The Runtime Interaction

Abstract explanations only go so far. The clearest way to understand how skills, commands, and agents coordinate is to trace a realistic example from start to finish.

Example: A PR Review Workflow

Imagine a developer is working on a pull request. They've finished their changes and want a comprehensive review before requesting feedback from teammates. They type /review-pr.

Step 1: Command activation. The /review-pr command fires. Claude Code loads the command's instructions and begins executing the defined workflow. The command's first job is to gather context — what files changed, what the diff looks like, what tests exist. It uses its allowed tools (Read, Bash(git:*), Glob, Grep) to pull together this information.

Step 2: Skill detection. As the command processes the diff, it encounters code patterns that match an active skill. The developer's plugin configuration includes a security-patterns skill whose description mentions activation when "reviewing code changes that touch authentication, session management, or external API calls." The diff touches an authentication flow. Claude recognizes the match and the skill becomes active for this part of the review.

Step 3: Skill execution. The security-patterns skill runs within the command's workflow. It reads the changed files using Read and searches for known vulnerability patterns using Grep. It identifies two potential issues: a JWT verification path that might be bypassable, and a place where user input flows into a SQL query without parameterization.

Step 4: Agent delegation. The skill recognizes that one of the identified issues — the JWT path — requires deeper analysis than it's set up to provide. The skill delegates to a security-reviewer agent, passing the specific code sections that need scrutiny. The agent runs in a fresh context with its narrow instructions, analyzes just the JWT verification flow, and returns a structured finding with severity rating and recommended fix.

Step 5: Output assembly. Control returns to the /review-pr command, which now has input from the general diff analysis, the security skill's pattern findings, and the security agent's detailed JWT analysis. The command assembles these into a structured review: architecture observations, code quality notes, test coverage gaps, and a dedicated security section with the agent's findings highlighted.

This coordination isn't automatic or magical. It requires deliberate design. The command author has to decide what skills might be relevant to the workflow. The skill author has to define clear delegation criteria for when to involve an agent. The agent author has to scope the agent's context tightly enough that it actually improves results rather than just adding latency.

Where Things Can Go Wrong

The three-layer model introduces coordination points where things can break down. Understanding the failure modes is as important as understanding the happy path.

Over-activation of skills. If a skill's description is too broad, it activates when it shouldn't — injecting its instructions into contexts where they're irrelevant or actively unhelpful. A skill described as "use when working with code" will activate almost constantly, diluting Claude's context with instructions designed for a narrow situation.

Command-skill conflicts. When a command and a skill both try to handle the same aspect of a workflow, the results can be inconsistent. The command expects to own the process; the skill activates autonomously and modifies behavior. Avoiding this requires careful description scoping — skills should describe when they're needed, not what they can do.

Excessive agent delegation. Delegating to an agent has a cost: it consumes additional context and adds latency. If an agent is invoked for work that a skill could handle directly, the overhead isn't justified. The 90% of plugins that skip agents have decided — correctly, in most cases — that their workflows don't require that level of specialization.

Why Most Plugins Skip Agents

The 10% agent adoption rate isn't a sign that agents are niche or poorly understood. It's a sign that they solve a specific problem, and most plugins don't have that problem.

Agents make sense when you have a genuinely distinct subtask — something that requires different instructions, different tool permissions, and ideally a fresh context to work well. The operative word is "distinct." If you can handle the subtask with a skill whose description is narrower, that's almost always the right call. Skills have lower overhead, simpler mental models, and fewer coordination points.

The plugins that use agents tend to fall into a few categories:

• Comprehensive review workflows. PR review, code audit, security analysis — workflows that have a general phase and then a specialist phase where a different kind of thinking is needed.
• Multi-stage generation. Creating documentation that requires both technical analysis (reading the code) and writing (producing the docs) as distinct passes with different contexts.
• Research + synthesis. Gathering information from multiple sources (agent handles research) and then synthesizing it into an artifact (parent skill handles synthesis).
• Validation pipelines. Running checks where each check is narrow enough to benefit from isolated context — a security agent, a performance agent, a style agent — rather than a single skill trying to do all three.

What these use cases share is a clear boundary between subtasks. When you can draw a clean line between "this part needs these tools and these instructions" and "that part needs those tools and those instructions," an agent might be worth it. When the workflow is more continuous — where skills naturally hand off to each other without needing isolated context — agents add complexity without adding value.

Design Recommendations

The data from 315 plugins points toward a consistent progression. Plugins that work well tend to follow the same pattern in how they incorporate these three content types.

Start With Skills

Every plugin that does anything should start with one or more skills. Skills are the ambient layer — they make Claude smarter in the domains your plugin covers without requiring any user action. A well-crafted skill with a precise description and appropriate tool permissions handles the common case elegantly.

Write the description before writing the instructions. Ask: "What will a user be doing when this skill should activate?" Express those scenarios in plain language. Then write instructions that handle those scenarios well.

If your plugin covers multiple distinct domains, give each one its own skill file. Don't bundle everything into a single SKILL.md — a monolithic skill with a broad description is worse than several focused skills with precise descriptions.

Add Commands for Explicit Entry Points

Once your skills are working well, look for workflows that users should be able to invoke explicitly — things where "do this now, on demand" is more useful than "do this when you think it's relevant." Those are command candidates.

Good commands have clear names that describe an action (/commit, /review-pr, /generate-docs). They represent workflows with obvious start and end points. They're things users would type deliberately, not things that should happen automatically.

Don't add commands just because you can. If a skill handles the use case well autonomously, a parallel command adds cognitive load without adding capability. The question to ask is: "Would a user ever want to invoke this explicitly, separate from the AI's judgment about when it's relevant?" If yes, add a command.

Agents Only for Complex Delegation

Agents are for situations where isolated context genuinely improves results. Before adding an agent, ask: "Is this subtask distinct enough — in terms of instructions, tools, and required focus — that isolating it in a fresh context will produce meaningfully better output?" If you're not confident the answer is yes, it probably isn't.

If you do add agents, keep their scope narrow. An agent that's trying to do too much will produce the same inconsistency as a skill with a vague description. Agents work best when they have a single clear responsibility and clear input/output contracts.

Document the delegation criteria explicitly in both the parent skill or command and the agent itself. Both sides of the delegation should express the same understanding of when delegation happens and what the agent is expected to produce.

Composition Patterns That Work

The skills-plus-commands pattern at 46.1% is the sweet spot for most serious plugins. It gives you ambient enhancement through skills and explicit control through commands, without the coordination overhead of agents. Most plugin authors who've shipped production-quality plugins land here.

The Numbers

To close, here's the complete picture of how each content type is adopted across the ecosystem. These figures come from analysis of 315 plugins actively maintained in the marketplace.

The progression from skills to commands to agents maps roughly to workflow complexity. Simple plugins that enhance Claude's domain knowledge stay at the skills layer. Plugins that offer user-facing workflows add commands. Plugins that orchestrate multi-phase processes with distinct specialist subtasks add agents. Each step is justified by the use case — not added because the capability exists.

This is the design principle the ecosystem has converged on through practice rather than prescription. The 5.7% of plugins that use all three content types didn't start there — they grew into that complexity as their workflows demanded it. Starting simple and adding complexity only when forced to by genuine requirements is how the best plugins in the ecosystem were built.

The interaction model described here is based on the 2026 SKILL.md spec and the current plugin structure for Claude Code. As the platform evolves, the coordination mechanisms between content types may change — but the underlying principle of separating ambient expertise (skills), explicit control (commands), and specialized delegation (agents) is likely to remain stable.