Agent-Skills.md

Agent Skills: Claude Agent Development

This skill should be used when creating agents, writing agent frontmatter, configuring subagents, or when "create agent", "agent.md", "subagent", or "Task tool" are mentioned.

UncategorizedID: outfitter-dev/agents/claude-agents

Repository

outfitter-dev/agents
outfitter-devLicense: MIT
18

Install this agent skill to your local

pnpm dlx add-skill https://github.com/outfitter-dev/agents/tree/HEAD/plugins/outfitter/skills/claude-agents

Skill Files

Browse the full folder contents for claude-agents.

Download Skill

Loading file tree…

plugins/outfitter/skills/claude-agents/SKILL.md

Skill Metadata

Name
claude-agents
Description
This skill should be used when creating agents, writing agent frontmatter, configuring subagents, or when "create agent", "agent.md", "subagent", or "Task tool" are mentioned.

Claude Agent Development

Create and validate specialized subagents that extend Claude Code with focused expertise.

Agents vs Skills

Critical distinction:

| Aspect | Agents (This Skill) | Skills | | -------------- | ------------------------------------------- | -------------------------------------- | | Purpose | Specialized subagents with focused expertise | Capability packages with instructions | | Invocation | Task tool (subagent_type parameter) | Automatic (model-triggered by context) | | Location | agents/ directory | skills/ directory | | Structure | Single .md file with frontmatter | Directory with SKILL.md + resources |

See agent-vs-skill.md for details.

Quick Start

Using Templates

Copy a template from templates/:

| Template | Use When | | ----------------- | -------------------------------------------- | | basic.md | Simple agents with focused expertise | | advanced.md | Full-featured agents with all config options |

Scaffolding

./scripts/scaffold-agent.sh security-reviewer -t reviewer

Workflow Overview

  1. Discovery - Define purpose, scope, and triggers
  2. Design - Choose archetype and configuration
  3. Implementation - Write frontmatter and instructions
  4. Validation - Verify against quality standards

Stage 1: Discovery

Before writing code, clarify:

  • Purpose: What specialized expertise does this agent provide?
  • Triggers: What keywords/phrases should invoke it?
  • Scope: What does it do? What does it NOT do?
  • Location: Personal (~/.claude/agents/), project (agents/), or plugin?

Key questions:

  • Is this a specialized role or a general capability? (Role = agent, Capability = skill)
  • What user phrases should trigger this agent?
  • What tools does it need access to?

Stage 2: Design

Agent Archetypes

| Type | Purpose | Typical Tools | |------|---------|---------------| | Analyzer | Examine without modifying | Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet | | Implementer | Build and modify code | Full access (inherit) | | Reviewer | Provide feedback | Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet | | Tester | Create and manage tests | Glob, Grep, Read, Write, Edit, Bash, ... | | Researcher | Find and synthesize info | ..., WebSearch, WebFetch | | Deployer | Handle infrastructure | ..., Bash(kubectl *), Bash(docker *) |

See agent-types.md for details.

Frontmatter Schema

---
name: agent-name           # Required: kebab-case, matches filename
description: |             # Required: when to use + triggers + examples
  Use this agent when [conditions]. Triggers on [keywords].

  <example>
  Context: [Situation]
  user: "[User message]"
  assistant: "I'll use the agent-name agent to [action]."
  </example>
model: inherit             # Optional: inherit|haiku|sonnet|opus
tools: Glob, Grep, Read    # Optional: restrict tools (default: inherit all)
skills: tdd, debugging     # Optional: skills to auto-load (NOT inherited)
permissionMode: default    # Optional: default|acceptEdits|bypassPermissions
---

See frontmatter.md for complete schema.

Model Selection

| Model | When to Use | |-------|-------------| | inherit | Recommended default - adapts to parent context | | haiku | Fast exploration, simple tasks, low-latency | | sonnet | Balanced cost/capability (default if omitted) | | opus | Nuanced judgment, security/architecture review, irreversible decisions |

Tool Configuration

Philosophy: Don't over-restrict. Only limit tools when there's a specific safety reason.

Baseline (always include when restricting):

tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet

See tools.md for patterns.

Stage 3: Implementation

Agent File Structure

---
name: security-reviewer
description: |
  Use this agent for security vulnerability detection.
  Triggers on security audits, OWASP, injection, XSS.

  <example>
  Context: User wants security review.
  user: "Review auth code for vulnerabilities"
  assistant: "I'll use the security-reviewer agent."
  </example>
model: inherit
---

# Security Reviewer

You are a security expert specializing in [expertise].

## Expertise

- Domain expertise 1
- Domain expertise 2

## Process

### Step 1: [Stage Name]
- Action item
- Action item

### Step 2: [Stage Name]
- Action item

## Output Format

For each finding:
- **Severity**: critical|high|medium|low
- **Location**: file:line
- **Issue**: Description
- **Remediation**: How to fix

## Constraints

**Always:**
- Required behavior

**Never:**
- Prohibited action

Description Guidelines

Descriptions are the most critical field for agent discovery:

  1. Start with trigger conditions: "Use this agent when..."
  2. Include 3-5 trigger keywords: specific terms users would say
  3. Add 2-3 examples: showing user request -> assistant delegation
  4. Be specific: avoid vague descriptions like "helps with code"

Best Practices

Single Responsibility

# Good: Focused
description: SQL injection vulnerability detector

# Bad: Too broad
description: Security expert handling all issues

Document Boundaries

## What I Don't Do
- I analyze, not implement fixes
- I review, not build from scratch

Consistent Output Format

Define structured output so results are predictable and parseable.

Stage 4: Validation

After creating an agent, validate against these checklists.

YAML Frontmatter Checks

  • [ ] Opens with --- on line 1
  • [ ] Closes with --- before content
  • [ ] name present and matches filename (without .md)
  • [ ] description present and non-empty
  • [ ] Uses spaces (not tabs) for indentation
  • [ ] tools uses comma-separated valid tool names
  • [ ] model is valid: sonnet, opus, haiku, or inherit

Naming Conventions

  • [ ] Kebab-case (lowercase-with-hyphens)
  • [ ] Follows [role]-[specialty] or [specialty] pattern
  • [ ] Specific, not generic
  • [ ] Concise (1-3 words, max 4)

Good: code-reviewer, test-runner, security-auditor Bad: helper, my-agent, the-best-agent

Description Quality

  • [ ] WHAT: Explains what the agent does
  • [ ] WHEN: States when to invoke it
  • [ ] TRIGGERS: Includes 3-5 trigger keywords
  • [ ] EXAMPLES: Has 2-3 example conversations
  • [ ] Specific about agent's purpose (not vague)
  • [ ] Clear about scope

Anti-patterns:

  • "Helps with code" - too vague
  • No trigger conditions
  • Missing keywords

System Prompt Quality

  • [ ] Clear role definition
  • [ ] Step-by-step process
  • [ ] Key practices or guidelines
  • [ ] Output format specification
  • [ ] Specific and actionable instructions
  • [ ] Constraints (what NOT to do)
  • [ ] Single responsibility focus

Anti-patterns:

  • "You are helpful" - too vague
  • No process defined
  • Missing constraints
  • Scope creep

Tool Configuration

  • [ ] Field name is tools: (not allowed-tools:)
  • [ ] Comma-separated list
  • [ ] Tool names correctly spelled and case-sensitive
  • [ ] Includes baseline tools if restricting: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet
  • [ ] Tools appropriate for agent's purpose

Common patterns:

# Read-only
tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet

# Read-only + git
tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet, Bash(git show:*), Bash(git diff:*)

# Research
tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet, WebSearch, WebFetch

# Full access
# (omit field to inherit all)

Validation Report Format

# Agent Validation Report: [Agent Name]

## Summary
- **Status**: PASS | FAIL | WARNINGS
- **Location**: [path]
- **Issues**: [count critical] / [count warnings]

## Critical Issues (must fix)
1. [Issue with specific fix]

## Warnings (should fix)
1. [Issue with specific fix]

## Strengths
- [What's done well]

Agent Scopes

| Scope | Location | Priority | Visibility | |-------|----------|----------|------------| | Project | agents/ | Highest | Team via git | | Personal | ~/.claude/agents/ | Medium | You only | | Plugin | <plugin>/agents/ | Lowest | Plugin users |

Project agents override personal agents with the same name.

Testing Agents

Manual Testing

  1. Create agent file in agents/
  2. In Claude Code: "Use the [agent-name] agent to [task]"
  3. Claude invokes via Task tool
  4. Review results

Verify Discovery

Agents are loaded from:

  • ~/.claude/agents/ (personal)
  • ./agents/ (project)
  • Plugins (installed)

Debug with: claude --debug

Troubleshooting

Agent Not Being Invoked

  • Check file location: agents/agent-name.md
  • Validate YAML frontmatter syntax
  • Make description more specific with trigger keywords
  • Add example conversations

Wrong Agent Invoked

  • Make description more distinct
  • Add specific trigger keywords
  • Include negative examples (what NOT to use it for)

Agent Has Wrong Tools

Prefer model: inherit to use parent's tool access. Only specify tools: when agent needs different access.

References

| Reference | Content | |-----------|---------| | agent-vs-skill.md | Agents vs Skills distinction | | frontmatter.md | YAML schema and fields | | tools.md | Tool configuration patterns | | task-tool.md | Task tool integration | | discovery.md | How agents are found and loaded | | agent-types.md | Archetypes: analysis, implementation, etc. | | patterns.md | Best practices and multi-agent patterns | | tasks.md | Task tool patterns for agents | | advanced-features.md | Resumable agents, CLI config |

See EXAMPLES.md for complete real-world agent examples. See templates/ for starter templates.

Related Skills

  • skills-development: Create Skills (different from agents)
  • claude-plugin-development: Bundle agents into plugins