home / skills / outfitter-dev / agents / claude-agents

claude-agents skill

needs review

This skill helps you create, configure, and document Claude agents and subagents, guiding frontmatter, task tool usage, and agent roles.

npx playbooks add skill outfitter-dev/agents --skill claude-agents

Review the files below or copy the command above to add this skill to your agents.

Files (15)

SKILL.md

10.7 KB

# Agent vs Skill

Critical distinction—agents and skills serve different purposes.

## Comparison

| Aspect | Agents | Skills |
|--------|--------|--------|
| **Location** | `agents/*.md` | `skills/*/SKILL.md` |
| **Structure** | Single markdown file | Directory with resources |
| **Invocation** | Explicit via Task tool | Automatic via context |
| **Parameter** | `subagent_type` in Task | N/A |
| **Scope** | Narrow, specialized | Broad capability |
| **Trigger** | "Use X agent to..." | Automatic on keywords |
| **Context** | Separate conversation | Main conversation |

## When to Use Agents

- Specialized expertise for specific task types
- Task requires separate context/conversation thread
- Compartmentalized work (security review, testing)
- Narrow specialization that shouldn't pollute main context
- Clear handoff between roles (review → implement → test)

## When to Use Skills

- Capabilities available throughout conversation
- Expertise applies to many task types
- Claude autonomously decides when to use it
- Capability is a tool/technique, not a role
- Resources (scripts, templates) need bundling

## Combined Usage

Use both together for layered capability:

```
# Skill: code-review (capability)
skills/code-review/SKILL.md
- Provides review techniques
- Available in all conversations
- Claude uses when reviewing

# Agent: security-reviewer (specialized role)
agents/security-reviewer.md
- Uses review techniques from skill
- Focused exclusively on security
- Invoked for security-specific reviews
```

## Quick Decision

```
Need specialized expertise for one task type?  → Agent
Need capability across many task types?        → Skill
Need both focused role AND broad technique?    → Both
```

Overview

This skill guides creation and configuration of agents and subagents, and helps author agent frontmatter and Task tool entries. It clarifies when to choose an agent vs a reusable capability and provides patterns for composing layered agent + capability setups. Use it to ensure agents are specialized, isolated, and clearly configured.

How this skill works

The skill inspects intents such as "create agent", "agent.md", "subagent", "Task tool", and frontmatter fields like subagent_type. It recommends structure, parameter usage, and handoff patterns so agents remain narrow and conversation-scoped while capabilities remain broadly available. It also shows how to combine agents with reusable capabilities for layered workflows.

When to use it

When you need a narrow, specialized role that runs in its own conversation thread
When authoring agent frontmatter or configuring subagents and their parameters
When deciding between a separate agent and a reusable capability
When creating a Task tool entry or setting subagent_type fields
When you need clear handoff points between review, implement, and test roles

Best practices

Keep agents narrowly scoped to avoid polluting the main conversation context
Use subagent_type in Task definitions to select the correct specialized agent
Model broad capabilities as reusable skills that Claude can call autonomously
Design clear interfaces and handoffs between agents and capabilities
Bundle scripts or templates with capabilities, not with narrow agents

Example use cases

Create a security-reviewer agent for isolated vulnerability analysis and handoff
Define a code-quality capability used across many agent types for consistent reviews
Configure a subagent for automated testing triggered by a Task tool entry
Write agent frontmatter specifying subagent_type and parameters for a QA workflow
Combine a general code-review capability with a specialized performance-tuner agent

FAQ

When should I create an agent instead of a capability?

Create an agent for narrow, role-specific tasks that require their own conversation and explicit invocation. Use a capability when the behavior should be available broadly across conversations.

How do I keep agents from duplicating capability logic?

Extract shared techniques and templates into reusable capabilities, then have agents call or reference those capabilities for consistent behavior and fewer duplicates.