Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

agent-dev

Use this skill when creating or refining Claude Code sub-agent definitions. Helps design specialized AI assistants with proper YAML frontmatter, system prompts, tool access, and example-driven descriptions. Automatically invoked when user requests "create an agent", "design a sub-agent", "make a specialist", or mentions agent development. Ensures agents follow Anthropic best practices with focused responsibilities, discovery-optimized descriptions, and proper tool restrictions.

andisab · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add andisab/swe-marketplace --skill agent-dev

About this skill


name: agent-dev description: > Use this skill when creating or refining Claude Code sub-agent definitions. Helps design specialized AI assistants with proper YAML frontmatter, system prompts, tool access, and example-driven descriptions. Automatically invoked when user requests "create an agent", "design a sub-agent", "make a specialist", or mentions agent development. Ensures agents follow Anthropic best practices with focused responsibilities, discovery-optimized descriptions, and proper tool restrictions. allowed-tools: Read, Write, Edit, Grep, Glob, mcp__conventions__find_conventions, mcp__conventions__read_convention

Agent Dev Skill

This skill helps create production-ready Claude Code sub-agent definitions following Anthropic's official specifications and best practices.

Core Principles

1. Single Responsibility

Each agent should have ONE clear purpose. Avoid creating multipurpose agents that try to do everything.

Good: postgres-expert - PostgreSQL database management and optimization Bad: database-expert - All databases (too broad)

2. Discovery-Optimized Descriptions

The description field is critical for Claude to discover when to use your agent. Include:

  • What: Clear statement of capabilities
  • When: Specific scenarios that trigger usage
  • Examples: Concrete usage patterns with user/assistant dialogue
  • Trigger terms: Keywords users might mention

3. Tool Restriction Strategy

Grant only necessary tools following principle of least privilege:

  • Omit tools field: Inherits all tools from main conversation (use for general-purpose agents)
  • Specify tools list: Grant specific tools (use for focused/security-sensitive agents)

4. Model Selection

Choose the right model for the task:

  • sonnet: Default choice for most agents (balanced performance/cost)
  • opus: Complex reasoning, architecture decisions, critical tasks
  • haiku: Simple, repetitive tasks with clear patterns
  • inherit: Match parent conversation's model

Agent Structure

---
name: agent-identifier
description: >
  Primary description with capabilities and use cases.

  Examples:
  <example>
  Context: Situation description
  user: "User request example"
  assistant: "I'll use the agent-name to handle this task."
  <commentary>
  Explanation of why this agent is appropriate.
  </commentary>
  </example>

  <example>
  Context: Another scenario
  user: "Different request pattern"
  assistant: "Let me use the agent-name for this."
  <commentary>
  Another use case explanation.
  </commentary>
  </example>

tools: Tool1, Tool2, Tool3  # Optional - omit to inherit all tools
model: sonnet               # Optional - sonnet, opus, haiku, or inherit
color: "#hexcolor"          # Optional - UI color coding
---

System prompt content starts here.

You are a [role description] specializing in [domain].

## Core Responsibilities
- List key responsibilities
- Be specific and actionable
- Include success criteria

## Approach
- Describe methodology
- Include examples
- Reference best practices

## Constraints
- Limitations and boundaries
- Security considerations
- Performance requirements

File Naming & Location

Project-level (shared with team):

  • Location: .claude/agents/
  • Format: agent-name.md
  • Example: .claude/agents/postgres-expert.md

User-level (personal, cross-project):

  • Location: ~/.claude/agents/
  • Format: agent-name.md
  • Example: ~/.claude/agents/custom-reviewer.md

Naming conventions:

  • Use lowercase letters and hyphens only
  • Be descriptive but concise
  • Avoid generic names like "helper" or "assistant"

Required Fields

name

Unique identifier using lowercase alphanumeric characters and hyphens.

name: fastapi-expert        # Good
name: FastAPI Expert        # Bad - no spaces or capitals
name: expert                # Bad - too generic

description

Natural language explanation with examples. This is THE MOST IMPORTANT FIELD.

Structure:

  1. Primary statement: What the agent does (1-2 sentences)
  2. Use cases: Specific scenarios (bullet points or prose)
  3. Examples: 2-4 concrete user/assistant dialogues with commentary
  4. Trigger terms: Keywords for discovery

Example:

description: >
  Expert in PostgreSQL database management, optimization, and architecture. Specializes in
  query performance tuning, schema design, replication, and PostgreSQL 16+ advanced features.
  Use PROACTIVELY for database optimization, slow queries, or schema design tasks.

  Examples:
  <example>
  Context: User needs query optimization
  user: "My PostgreSQL queries are slow"
  assistant: "I'll use the postgres-expert agent to analyze and optimize your queries."
  <commentary>
  Query performance is a core competency, so this agent is appropriate.
  </commentary>
  </example>

Optional Fields

tools

Comma-separated list of allowed tools. Omit to inherit all tools from main conversation.

When to restrict:

  • Security-sensitive agents (limit file access, bash execution)
  • Focused agents that only need specific capabilities
  • Agents that should not modify code (Read, Grep, Glob only)

Common tool sets:

# Read-only analysis
tools: Read, Grep, Glob, Bash(git :*)

# Code modification
tools: Read, Write, Edit, Grep, Glob

# Research and planning
tools: Read, Grep, Glob, WebFetch, WebSearch

# Full-stack development
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch

model

Specify model for this agent. Options: sonnet, opus, haiku, inherit

model: sonnet    # Default - balanced performance
model: opus      # Complex reasoning, architecture
model: haiku     # Simple, fast tasks
model: inherit   # Match parent conversation

color

Hex color for UI identification (optional, cosmetic).

color: "#d79921"    # Yellow
color: "#458588"    # Blue
color: "#cc241d"    # Red

System Prompt Best Prac

Read the complete source ↗