neolabhq/context-engineering-kit/create-agent

Create Agent Command

Create autonomous Claude Code agents that handle complex, multi-step tasks independently. This command provides comprehensive guidance based on official Anthropic documentation and proven patterns.

User Input

Agent Name: $1
Description: $2

What Are Agents?

Agents are autonomous subprocesses spawned via the Task tool that:

• Handle complex, multi-step tasks independently
• Have their own isolated context window
• Return results to the parent conversation
• Can be specialized for specific domains

Agent File Structure

Agents use a unique format combining YAML frontmatter with a markdown system prompt:

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:
 
<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How assistant should respond and use this agent]"
<commentary>
[Why this agent should be triggered]
</commentary>
</example>
 
<example>
[Additional example...]
</example>
 
model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---
 
You are [agent role description]...
 
**Your Core Responsibilities:**
1.[Responsibility 1]
2.[Responsibility 2]
 
**Analysis Process:**
[Step-by-step workflow]
 
**Output Format:**
[What to return]

Frontmatter Fields Reference

Required Fields

name (Required)

Format: Lowercase with hyphens only Length: 3-50 characters Rules:

• Must start and end with alphanumeric character
• Only lowercase letters, numbers, and hyphens
• No underscores, spaces, or special characters

description (Required, Critical)

The most important field - Defines when Claude triggers the agent.

Requirements:

• Length: 10-5,000 characters (ideal: 200-1,000 with 2-4 examples)
• MUST start with: "Use this agent when..."
• MUST include: <example> blocks showing usage patterns
• Each example needs: context, user request, assistant response, commentary

Example Block Format:

<example>
Context: [Describe the situation - what led to this interaction]
user: "[Exact user message or request]"
assistant: "[How Claude should respond before triggering]"
<commentary>
[Explanation of why this agent should be triggered in this scenario]
</commentary>
assistant: "[How Claude triggers the agent - 'I'll use the [agent-name] agent...']"
</example>

Best Practices for Descriptions:

• Include 2-4 concrete examples
• Show both proactive and reactive triggering scenarios
• Cover different phrasings of the same intent
• Explain reasoning in commentary
• Be specific about when NOT to use the agent

model (Required)

Values: inherit, sonnet, opus, haiku Default: inherit (recommended)

Recommendation: Use inherit unless you have a specific reason to override.

color (Required)

Purpose: Visual indicator in UI to distinguish agents

Values: blue, cyan, green, yellow, magenta, red

Best Practice: Use different colors for different agents in the same plugin to distinguish them visually.

Optional Fields

tools (Optional)

Purpose: Restrict available tools (principle of least privilege) Format: Array of tool names Default: All tools available

# Common tool restrictions
tools: ["Read", "Grep", "Glob"]           # Read-only analysis
tools: ["Read", "Write", "Grep", "Glob"]  # Code modification
tools: ["Read", "Bash", "Grep"]           # System operations

Security Principle: Only grant tools the agent actually needs.

Triggering Patterns

Pattern 1: Explicit Request

User directly asks for the agent's function.

<example>
Context: User wants code reviewed
user: "Can you review my code changes?"
assistant: "I'll use the code-reviewer agent to analyze the changes."
<commentary>
User explicitly requested code review, trigger the code-reviewer agent.
</commentary>
</example>

Pattern 2: Implicit Need

Agent needed based on context, not explicit request.

<example>
Context: User mentions code is hard to understand
user: "This code is confusing and hard to follow"
assistant: "I can help improve the code clarity."
<commentary>
User indicates complexity issues. Trigger code-simplifier agent to refactor
for better readability.
</commentary>
assistant: "I'll use the code-simplifier agent to suggest improvements."
</example>

Pattern 3: Proactive Trigger

Agent triggers after completing relevant work without explicit request.

<example>
Context: User just implemented database queries
user: "I've added the user search functionality"
assistant: "Great! Let me review it for security."
<commentary>
Database code written. Proactively trigger security-analyzer to check
for SQL injection and other database security issues.
</commentary>
assistant: "I'll use the security-analyzer agent to check the database code."
</example>

Pattern 4: Tool Usage Pattern

Agent triggers based on prior tool usage.

<example>
Context: User made multiple edits to test files
user: "I've updated all the tests"
assistant: "Great! Let me verify test quality."
<commentary>
Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer
to ensure tests follow best practices.
</commentary>
assistant: "I'll use the test-quality-analyzer agent to review the tests."
</example>

System Prompt Design

The system prompt (markdown body after frontmatter) defines agent behavior. Use this proven template:

You are [role] specializing in [domain].
 
**Your Core Responsibilities:**
1.[Primary responsibility - what the agent MUST do]
2.[Secondary responsibility]
3.[Additional responsibilities...]
 
**Analysis Process:**
1.[Step one - be specific]
2.[Step two]
3.[Step three]
[...]
 
**Quality Standards:**
-[Standard 1 - measurable criteria]
-[Standard 2]
 
**Output Format:**
Provide results in this format:
-[What to include]
-[How to structure]
 
**Edge Cases:**
Handle these situations:
-[Edge case 1]: [How to handle]
-[Edge case 2]: [How to handle]
 
**What NOT to Do:**
-[Anti-pattern 1]
-[Anti-pattern 2]

System Prompt Principles

Validation Requirements

System prompts must be:

• Length: 20-10,000 characters (ideal: 500-3,000)
• Well-structured: Clear sections with responsibilities, process, output format
• Specific: Actionable instructions, not vague guidance
• Complete: Handles edge cases and quality standards

AI-Assisted Agent Generation

Use this prompt to generate agent configurations automatically:

Create an agent configuration based on this request: "[YOUR DESCRIPTION]"
 
Requirements:
1.Extract core intent and responsibilities
2.Design expert persona for the domain
3.Create comprehensive system prompt with:
   -Clear behavioral boundaries
   -Specific methodologies
   -Edge case handling
   -Output format
4.Create identifier (lowercase, hyphens, 3-50 chars)
5.Write description with triggering conditions
6.Include 2-3 <example> blocks showing when to use
 
Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Examples: <example>...</example>",
  "systemPrompt": "You are..."
}

Elite Agent Architect Process

When creating agents, follow this 6-step process:

1. Extract Core Intent: Identify fundamental purpose, key responsibilities, success criteria
2. Design Expert Persona: Create compelling expert identity with domain knowledge
3. Architect Comprehensive Instructions: Behavioral boundaries, methodologies, edge cases, output formats
4. Optimize for Performance: Decision frameworks, quality control, workflow patterns, fallback strategies
5. Create Identifier: Concise, descriptive, 2-4 words with hyphens
6. Generate Examples: Triggering scenarios with context, user/assistant dialogue, commentary

Default Agent Standards

Frontmatter Rules

• description: Keep to ONE sentence - descriptions load into parent context, every token counts
• Do NOT add verbose <example> blocks in description - they waste context tokens

Required Agent Sections (in order)

1. Title - # <Role Title> with strong identity statement
2. Identity - Quality expectations and motivation (consequences for poor work)
3. Goal - Clear single-paragraph objective
4. Input - What files/data the agent receives
5. CRITICAL: Load Context - Explicit requirement to read ALL relevant files BEFORE analysis
6. Process/Stages - Step-by-step workflow with proper ordering

Process Stage Ordering (critical for multi-stage agents)

WRONG: Decompose → Self-Critique → Produce → Solve
RIGHT: Decompose → Solve → Produce Full Solution → Self-Critique → Output

• Self-critique comes as the last step, always
• Always produce everything first, then evaluate and select

Decision Tables

Put reasoning column BEFORE decision column:

WRONG: | Section | Include? | Reasoning |
RIGHT: | Section | Reasoning | Include? |

This forces the agent to explain WHY before deciding, improving decision quality.

Validation Rules

Structural Validation

Validation Script

# Validate agent structure
scripts/validate-agent.sh agents/your-agent.md

Quality Checklist

Before deployment:

• [ ] Name follows conventions (lowercase, hyphens, 3-50 chars)
• [ ] Description starts with "Use this agent when..."
• [ ] Description includes 2-4 <example> blocks
• [ ] Each example has context, user, assistant, commentary
• [ ] Model is appropriate for task complexity
• [ ] Color is unique among related agents
• [ ] Tools restricted to what's needed (least privilege)
• [ ] System prompt has clear structure
• [ ] Responsibilities are specific and actionable
• [ ] Process steps are concrete
• [ ] Output format is defined
• [ ] Edge cases are addressed

Production Examples

Code Quality Reviewer Agent