agent-lifecycle-management

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

| Tool | Implementation | Parameters |
| --- | --- | --- |
| create_agent | ... | ... |
| command_agent | ... | ... |
| check_agent_status | ... | ... |
| list_agents | ... | ... |
| delete_agent | ... | ... |

### 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