Agent Lifecycle Management Skill

Manage agent fleets through Create, Command, Monitor, and Delete operations.

Purpose

Guide the implementation of CRUD operations for agent fleets, ensuring proper lifecycle management and resource cleanup.

When to Use

• Setting up agent lifecycle patterns

• Implementing agent management tools

• Designing cleanup and resource management

• Building agent state tracking

Prerequisites

• Understanding of orchestrator architecture (@single-interface-pattern.md)

• Familiarity with the Three Pillars (@three-pillars-orchestration.md)

• Access to Claude Agent SDK documentation

SDK Requirement

Implementation Note: Full lifecycle management requires Claude Agent SDK with custom MCP tools. This skill provides design patterns for SDK implementation.

Lifecycle Pattern

Create --> Command --> Monitor --> Aggregate --> Delete | | | | | v v v v v Template Prompt Status Results Cleanup

CRUD Operations

Create Operation

Spin up a new specialized agent.

Parameters:

• template : Pre-defined configuration to use

• name : Unique identifier for this agent

• system_prompt : Custom prompt (alternative to template)

• model : haiku, sonnet, or opus

• allowed_tools : Tools this agent can use

Example:

create_agent( name="scout_1", template="scout-fast", # OR system_prompt="...", model="haiku", allowed_tools=["Read", "Glob", "Grep"] )

Best Practices:

• Use templates for consistency

• Give descriptive names

• Select appropriate model

• Minimize tool access

Command Operation

Send prompts to an agent.

Parameters:

• agent_id : Which agent to command

• prompt : The detailed instruction

Example:

command_agent( agent_id="scout_1", prompt=""" Analyze the authentication module in src/auth/. Focus on: 1. Current implementation patterns 2. Security considerations 3. Potential improvements

Report findings in structured format.
"""

)

Best Practices:

• Detailed, specific prompts

• Clear expected output format

• Include all relevant context

• One task per command

Monitor Operation (Read)

Check agent status and progress.

Operations:

Check status

check_agent_status( agent_id="scout_1", verbose_logs=True )

List all agents

list_agents()

Read agent logs

read_agent_logs( agent_id="scout_1", offset=0, limit=50 )

Status Values:

Status Meaning

idle

Ready for commands

executing

Processing prompt

waiting

Waiting for input

blocked

Permission needed

complete

Finished

Delete Operation

Clean up agents when work is complete.

Example:

delete_agent(agent_id="scout_1")

Key Principle:

"Treat agents as deletable temporary resources that serve a single purpose."

Lifecycle Patterns

Scout-Build Pattern

1. Create scout agent

2. Command: Analyze codebase

3. Monitor until complete

4. Aggregate scout findings

5. Delete scout

6. Create builder agent

7. Command: Implement based on findings

8. Monitor until complete

9. Aggregate build results

10. Delete builder

Scout-Build-Review Pattern

Phase 1: Scout

• Create scouts (parallel)
• Command each with specific area
• Aggregate findings

Phase 2: Build

• Create builder
• Command with scout reports
• Monitor implementation

Phase 3: Review

• Create reviewer
• Command to verify implementation
• Generate final report

Cleanup: Delete all agents

Parallel Execution

Create: scout_1, scout_2, scout_3 (parallel) Command each with different area Monitor all until complete Aggregate all findings Delete all scouts

Create: builder_1, builder_2 (parallel) Command each with different files Monitor all until complete Aggregate all changes Delete all builders

Agent Templates

Fast Scout Template

name: scout-fast description: Quick codebase reconnaissance tools: [Read, Glob, Grep] model: haiku

Scout Agent

Analyze codebase efficiently. Focus on:

• File structure
• Key patterns
• Relevant code sections

Report findings concisely.

Builder Template

name: builder description: Code implementation specialist tools: [Read, Write, Edit, Bash] model: sonnet

Builder Agent

Implement changes based on specifications. Follow existing patterns. Test your changes. Report what was modified.

Reviewer Template

name: reviewer description: Code review and verification tools: [Read, Grep, Glob, Bash] model: sonnet

Reviewer Agent

Verify implementation against requirements. Check for issues and risks. Report findings by severity.

State Tracking

Track agent state for observability:

{ "agent_id": "scout_1", "template": "scout-fast", "status": "executing", "created_at": "2024-01-15T10:30:00Z", "last_activity": "2024-01-15T10:32:15Z", "context_tokens": 12500, "cost": 0.05, "tool_calls": 15 }

Resource Cleanup

Cleanup Triggers

Trigger Action

Work complete Delete immediately

Error state Delete and report

Timeout Delete and warn

User abort Delete all

Cleanup Checklist

• All agents have termination logic

• Dead agents are detected

• Resources are released

• Final results are captured

• Cleanup is logged

Output Format

When implementing lifecycle management, provide:

Lifecycle Implementation

Agent Templates

[List of templates with configurations]

CRUD Tools

State Schema

[JSON schema for agent state]

Cleanup Logic

[When and how agents are deleted]

Anti-Patterns

Anti-Pattern Problem Solution

Keeping dead agents Resource waste Delete when done

Long-lived agents Context accumulation Fresh agents per task

Generic agents Unfocused work Specialized templates

Missing cleanup Dead agents accumulate Always delete

Reusing agents Context contamination Create fresh

Key Quotes

"The rate at which you create and command your agents becomes the constraint of your engineering output."

"One agent, one prompt, one purpose - then delete."

Cross-References

• @agent-lifecycle-crud.md - Lifecycle patterns

• @three-pillars-orchestration.md - CRUD pillar

• @single-interface-pattern.md - Orchestrator architecture

• @orchestrator-design skill - System design

Version History

• v1.0.0 (2025-12-26): Initial release

Last Updated

Date: 2025-12-26 Model: claude-opus-4-5-20251101