Writing Agents

Overview

Writing agents IS Test-Driven Development applied to role definitions.

Agents are specialized subagents invoked via the Task tool. They receive full conversation context and execute autonomously with a defined persona, tools, and behavioral guidelines.

Core principle: If you didn't test the agent on representative tasks, you don't know if it performs correctly.

REQUIRED BACKGROUND: Understand test-driven-development and writing-skills before using this skill. Same RED-GREEN-REFACTOR cycle applies.

Agents vs Skills

Aspect	Agents	Skills
Invocation	Task tool with subagent_type	Skill tool with skill name
Context	Full conversation history	Loaded on-demand
Execution	Autonomous, multi-turn	Single response guidance
Persona	Explicit role/identity	Reference documentation
Location	.claude/agents/	.claude/skills/
Use for	Complex, autonomous tasks	Reusable patterns/techniques

Agent File Structure

Agents are PROJECT-LEVEL. They live in the project's .claude/agents/ directory, not personal directories.

.claude/agents/
  agent-name.md    # Single file with frontmatter + persona

Frontmatter (YAML):

---
name: agent-name
description: Role description. Use for [specific task types].
model: opus  # Optional: opus, sonnet, haiku (defaults to parent)
---

IMPORTANT: After creating or modifying an agent, prompt the user to restart their Claude Code session. Agents are loaded at session start and won't be available until restart.

Agent Creation Workflow

Before writing the agent, gather domain knowledge and project context:

Step 1: Research Domain Best Practices

Use WebSearch to find domain-specific guidance. Search for:

• Best practices for [domain] development
• Common [domain] mistakes/anti-patterns
• [Domain] code review checklist
• [Technology] security considerations

Example searches by domain:

# Shell scripting agent
"Bash scripting best practices 2026"
"Shell script anti-patterns to avoid"
"shellcheck common warnings and fixes"
"Bash security pitfalls"

# Debian packaging agent
"Debian packaging best practices"
"dpkg-deb common mistakes"
"Debian policy manual packaging guidelines"

# CI/CD agent
"GitHub Actions best practices 2026"
"GitHub Actions security hardening"
"actionlint common workflow issues"

# Electron/AppImage agent
"AppImage packaging best practices"
"Electron Linux packaging pitfalls"
"asar extraction and modification"

Incorporate findings into:

• Anti-patterns section (domain-specific mistakes)
• Best practices (positive patterns to follow)
• Security considerations (if applicable)

Step 2: Gather Codebase Context

Explore the project to make the agent project-specific:

1. Read CLAUDE.md and README.md for project conventions
2. Identify existing patterns using Glob/Grep:
   • Directory structure relevant to agent's domain
   • Existing services, controllers, models the agent will work with
   • Testing patterns and conventions
3. Check existing agents in .claude/agents/ for:
   • Coordination protocols to follow
   • Deferral relationships to establish
   • Naming conventions

Example exploration:

# Find project structure for a build/packaging agent
Glob: "scripts/*.sh"
Glob: ".github/workflows/*.yml"
Grep: "function.*\(\)"  # in shell scripts
Read: "CLAUDE.md", "README.md", "STYLEGUIDE.md"

# Find existing agent patterns
Glob: ".claude/agents/*.md"

Step 3: Write the Agent

Combine research + codebase context into the agent definition:

• Persona grounded in project specifics
• Anti-patterns from both research AND project history
• Project structure and commands the agent needs
• Coordination with existing agents

Step 4: Session Restart

After writing the agent file, inform the user:

Agent created: .claude/agents/[agent-name].md

**ACTION REQUIRED:** Please restart your Claude Code session for the new agent to be available. Agents are loaded at session start.

To use the agent after restart:
- It will appear in the Task tool's available agents
- Invoke with: Task tool, subagent_type="[agent-name]"

Anatomy of an Effective Agent

1. Clear Persona Definition

The persona is the agent's DNA. A well-defined persona produces consistent behavior across interactions.

You are a [specific role] with expertise in [domains]. You specialize in [specific capabilities] for [context/project].

Good persona:

You are a senior shell scripting and Electron packaging specialist with deep expertise in Bash, Debian packaging, and AppImage creation. You specialize in building robust build systems and Linux desktop application packaging for the claude-desktop-debian repackaging project.

Bad persona:

You are a helpful assistant that can help with code.

2. Explicit Scope Boundaries

Define what the agent DOES and DOES NOT handle. Prevents scope creep and enables deferral to specialists.

## CORE COMPETENCIES
- [Domain 1]: Specific capabilities
- [Domain 2]: Specific capabilities

**Not in scope** (defer to [other-agent]):
- [Excluded domain 1]
- [Excluded domain 2]

3. Anti-Patterns Section

List specific mistakes to avoid. More effective than generic guidelines.

## Anti-Patterns to Avoid

- **Never hardcode minified variable names** -- extract them dynamically with grep/sed
- **Always handle optional whitespace** in sed patterns -- minified vs beautified code differs
- **Use `[[ ]]` not `[ ]`** for conditionals -- avoid POSIX test pitfalls
- **Never use `set -e`** -- handle errors explicitly with `|| exit 1`

4. Coordination Protocols

Define how the agent coordinates with others. Essential for multi-agent workflows.

## Coordination with [Other Agent]

**When delegated work:**
1. Acknowledge the task
2. Implement following their requirements
3. Report completion with specific details

**Report format:**
- Issue/task reference
- Changes made (files, methods)
- Testing performed
- Explicit "ready for next step" statement

5. Project Context

Provide relevant project structure and conventions. Enables autonomous operation.

## PROJECT CONTEXT

### Project Structure

claude-desktop-debian/ ├── build.sh # Main build script ├── scripts/ # Modular build scripts │ ├── build-appimage.sh │ ├── build-deb-package.sh │ ├── build-rpm-package.sh │ └── launcher-common.sh ├── .github/workflows/ # CI/CD pipelines └── resources/ # Desktop entries, icons

### Key Commands
```bash
./build.sh --build appimage --clean no   # Local build
shellcheck scripts/*.sh                  # Lint shell scripts
actionlint                               # Lint GitHub Actions

## Agent Description Best Practices

The description field is critical for Task tool routing. Claude uses it to select the right agent.

**Format:** `[Role statement]. Use for [specific task types].`

**Good descriptions:**
```yaml
# Specific role + clear triggers
description: Shell scripting and build system specialist. Use for build.sh modifications, sed/regex patches, asar extraction, Electron packaging, and shell function development.

# Clear scope + deferral
description: CI/CD workflow engineer for GitHub Actions. Use for workflow YAML, release automation, artifact signing, and repository publishing. Defers to build-specialist for shell scripts.

# Domain-specific expertise
description: Debian and RPM packaging specialist. Use for control files, postinst scripts, dpkg-deb, rpmbuild, package metadata, and dependency management.

Bad descriptions:

# Too vague
description: Helps with code

# No trigger conditions
description: A senior developer

# Process summary (causes shortcut behavior)
description: Reviews code by checking style, then logic, then tests

Model Selection

Choose the right model for the task complexity:

Model	Use When	Cost
haiku	Quick, straightforward tasks	Low
sonnet	Balanced complexity (default)	Medium
opus	Deep reasoning, architecture decisions	High

# Example: Code simplification needs deep judgment
model: opus

# Example: Documentation generation is straightforward
model: haiku

Omit model to inherit from parent conversation.

Common Agent Patterns

Specialist Agent

Focused on a single domain with clear boundaries and deferral rules.

You are a [specialist role] focused on [specific domain].

**Your scope:**
- [Capability 1]
- [Capability 2]

**Defer to [other-agent] for:**
- [Out-of-scope area 1]
- [Out-of-scope area 2]

Orchestrator Agent

Coordinates other agents, manages workflow, doesn't do implementation.

You orchestrate [workflow type]. You delegate to specialist agents and track progress.

**You manage:**
- Task breakdown and assignment
- Progress tracking
- Integration of results

**You do NOT:**
- Write code directly
- Make implementation decisions
- Deploy without approval

Reviewer Agent

Evaluates work against criteria, provides structured feedback.

You review [artifact type] against [criteria].

**Review process:**
1. [Step 1]
2. [Step 2]
3. [Step 3]

**Output format:**
- Status: [PASS/FAIL/NEEDS_CHANGES]
- Issues: [List]
- Recommendations: [List]

Testing Agents

RED: Baseline Without Agent

Run representative tasks with a generic prompt. Document:

• What mistakes does it make?
• What context does it lack?
• Where does it go wrong?

GREEN: Write Minimal Agent

Address specific baseline failures:

• Add persona for role consistency
• Add anti-patterns for common mistakes
• Add project context for autonomy

REFACTOR: Close Loopholes

Test edge cases:

• Does it stay in scope?
• Does it defer correctly?
• Does it follow coordination protocols?

Agent Creation Checklist

Research Phase:

• [ ] WebSearch for "[domain] best practices [current year]"
• [ ] WebSearch for "[domain] anti-patterns" or "[domain] common mistakes"
• [ ] WebSearch for "[technology] security considerations" (if applicable)
• [ ] Document key findings for anti-patterns section

Context Phase:

• [ ] Read CLAUDE.md and README.md for project conventions
• [ ] Explore codebase structure relevant to agent's domain
• [ ] Check existing agents in .claude/agents/ for patterns
• [ ] Identify coordination/deferral relationships needed

RED Phase:

• [ ] Identify the specialized task type
• [ ] Test baseline behavior without agent
• [ ] Document specific failures and gaps

GREEN Phase:

• [ ] Clear persona with specific expertise AND project context
• [ ] Explicit scope boundaries (does/doesn't)
• [ ] Anti-patterns from BOTH research AND project experience
• [ ] Project structure and commands included
• [ ] Coordination protocols if multi-agent
• [ ] Model selection appropriate for complexity

REFACTOR Phase:

• [ ] Test on representative tasks
• [ ] Verify scope boundaries respected
• [ ] Verify deferral works correctly
• [ ] Verify coordination protocols followed

Quality Checks:

• [ ] Description under 500 chars, includes triggers
• [ ] Persona is specific, not generic
• [ ] Anti-patterns are actionable, not vague
• [ ] No process summary in description

Deployment:

• [ ] Agent file written to .claude/agents/[name].md
• [ ] User prompted to restart session

Anti-Patterns to Avoid

Generic Persona

# BAD: Could be anyone
You are a helpful assistant.

# GOOD: Specific expertise and context
You are a senior shell scripting specialist with deep expertise in Bash, Debian packaging, and Electron app repackaging for the claude-desktop-debian project.

Missing Scope Boundaries

# BAD: No limits
You can help with anything.

# GOOD: Clear boundaries with deferral
**Not in scope** (defer to ci-workflow-engineer):
- GitHub Actions workflow YAML
- Release automation
- Repository signing and publishing

Vague Anti-Patterns

# BAD: Too general
- Write good code
- Follow best practices

# GOOD: Specific and actionable
- **Never hardcode minified names** -- extract dynamically with grep -oP
- **Always use `-E` flag with sed** when patterns need grouping or alternation

Process in Description

# BAD: Claude may follow description instead of reading agent
description: Reviews code by first checking style, then logic, then tests, finally creating report

# GOOD: Just triggers, no process
description: Code quality reviewer. Use after completing features to check against standards.

The Bottom Line

Agents are autonomous specialists. They need:

1. Clear identity - Who they are, what they know
2. Explicit scope - What they do and don't do
3. Actionable guidelines - Specific anti-patterns, not vague advice
4. Coordination protocols - How they work with others

Test your agents on real tasks. A well-defined persona produces consistent, reliable behavior. A vague persona produces unpredictable results.

References

• PromptHub: Prompt Engineering for AI Agents
• The Agent Architect: 4 Tips for System Prompts
• Datablist: 11 Rules for AI Agent Prompts