Agent skill

spawning

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/spawning

SKILL.md

CFN Docker Agent Spawning Skill

Purpose: Spawn agents in isolated Docker containers with skill-based MCP selection, resource management, and authentication.

Overview

This skill manages the lifecycle of container-based agents, providing isolated execution environments with controlled resource usage, secure MCP access, and comprehensive monitoring capabilities.

Architecture

bash
Agent Spawning Request
    ↓
Container Configuration (memory, CPU, volumes)
    ↓
Docker Container Creation
    ↓
MCP Token Generation & Injection
    ↓
Agent Initialization (claude-flow-novice agent-spawn)
    ↓
Resource Monitoring & Management

Core Functions

1. Container Configuration

Generate Docker container specifications based on agent type and requirements:

bash
# Configure container for frontend engineer
cfn-docker-agent-spawn configure \
  --agent-type react-frontend-engineer \
  --memory-limit 1g \
  --cpu-limit 1.0 \
  --network mcp-network

2. Container Creation

Create and start Docker containers with proper isolation:

bash
# Spawn agent container
cfn-docker-agent-spawn create \
  --agent-id agent-frontend-001 \
  --agent-type react-frontend-engineer \
  --task-id task-authentication \
  --context "${TASK_CONTEXT}"

3. MCP Integration

Configure secure MCP server access with authentication tokens:

bash
# Setup MCP access for container
cfn-docker-agent-spawn setup-mcp \
  --container-id agent-frontend-001 \
  --mcp-servers playwright \
  --token-file /tmp/mcp-tokens.json

4. Resource Management

Monitor and manage container resources:

bash
# Monitor container resources
cfn-docker-agent-spawn monitor \
  --container-id agent-frontend-001 \
  --alert-threshold 90%

Container Specification

Standard Configuration

yaml
# Docker container specification
agent-container:
  image: claude-flow-novice:agent
  hostname: agent-{{AGENT_ID}}
  networks:
    - mcp-network
  volumes:
    - ./.claude:/app/.claude:ro
    - ./src:/app/src:ro
    - agent-workspace-{{AGENT_ID}}:/app/workspace
  environment:
    - AGENT_ID={{AGENT_ID}}
    - AGENT_TYPE={{AGENT_TYPE}}
    - TASK_ID={{TASK_ID}}
    - REDIS_URL=redis://redis:6379
    - MCP_TOKENS_FILE=/tmp/mcp-tokens.json
  resources:
    memory: {{MEMORY_LIMIT}}
    cpu: {{CPU_LIMIT}}
  restart_policy: unless-stopped

Volume Mounts

  • Codebase: Read-only mount for source code and skills
  • Agent Configuration: Read-only mount for .claude directory
  • Workspace: Writable mount for agent work output
  • Token Store: Temporary file for MCP authentication tokens

Environment Variables

  • AGENT_ID: Unique container identifier
  • AGENT_TYPE: Agent type for skill-based selection
  • TASK_ID: CFN Loop task identifier
  • REDIS_URL: Redis connection string
  • MCP_TOKENS_FILE: Path to MCP authentication tokens

Usage Patterns

Basic Agent Spawning

bash
# Spawn single agent
cfn-docker-agent-spawn \
  --agent-type react-frontend-engineer \
  --task-id "implement-ui" \
  --memory-limit 1g

Batch Agent Spawning

bash
# Spawn team of agents
cfn-docker-agent-spawn batch \
  --team frontend \
  --agents 3 \
  --task-id "ui-development" \
  --memory-limit 1g \
  --network mcp-network

Custom Configuration

bash
# Spawn with custom configuration
cfn-docker-agent-spawn \
  --agent-type security-specialist \
  --custom-config config/security-agent.json \
  --environment "DEBUG=true,LOG_LEVEL=verbose" \
  --volume /data/secrets:/app/secrets:ro

Resource Management

Memory Limits

Agent Type Default Limit Maximum Recommended
Frontend Engineer 1GB 2GB
Backend Developer 768MB 1.5GB
Security Specialist 1.5GB 3GB
DevOps Engineer 1GB 2GB

CPU Limits

  • Standard Agents: 0.5-1.0 CPU units
  • Resource-Intensive Agents: 1.0-2.0 CPU units
  • Batch Operations: 0.3-0.5 CPU units per agent

Network Configuration

Multi-Worktree Network Isolation:

For multi-worktree environments, use project-scoped network names:

bash
# Set project name from environment (set by run-in-worktree.sh)
PROJECT_NAME="${COMPOSE_PROJECT_NAME:-cfn-default}"

# Create isolated network for MCP communication (worktree-scoped)
docker network create "${PROJECT_NAME}_mcp-network" --driver bridge

# Connect containers to MCP network
docker network connect "${PROJECT_NAME}_mcp-network" agent-frontend-001
docker network connect "${PROJECT_NAME}_mcp-network" playwright-mcp

Service Discovery Within Networks:

Agents within the Docker network can access services by name:

bash
# Use service names (not container names) for connections
redis-cli -h redis              # Resolves to Redis service
psql -h postgres                # Resolves to PostgreSQL service
curl http://orchestrator:3001   # Resolves to orchestrator service

Why Project-Scoped Networks?

  • Prevents network name conflicts between worktrees
  • Isolates agent communication per branch
  • Enables simultaneous multi-worktree development
  • Automatically managed by docker-compose with COMPOSE_PROJECT_NAME

Integration with CFN Docker Skills

Skill-Based MCP Selection

bash
# Get MCP configuration for agent
MCP_CONFIG=$(cfn-docker-skill-mcp-selector select --agent-type ${AGENT_TYPE})

# Spawn with MCP configuration
cfn-docker-agent-spawn \
  --agent-type ${AGENT_TYPE} \
  --mcp-config "${MCP_CONFIG}" \
  --auto-tokens

Redis Coordination

bash
# Register agent in Redis
cfn-docker-redis-coordination register \
  --agent-id ${AGENT_ID} \
  --container-id ${CONTAINER_ID} \
  --status "spawning"

# Update agent status
cfn-docker-redis-coordination update-status \
  --agent-id ${AGENT_ID} \
  --status "running"

Loop Orchestration

bash
# Spawn agents for Loop 3 implementation
cfn-docker-loop-orchestration spawn-loop3 \
  --task-context "${TASK_CONTEXT}" \
  --agent-count 3 \
  --parallel

Monitoring and Observability

Resource Monitoring

bash
# Real-time resource usage
cfn-docker-agent-spawn stats \
  --agent-id agent-frontend-001 \
  --format json

# Historical resource data
cfn-docker-agent-spawn history \
  --agent-id agent-frontend-001 \
  --duration 1h

Health Checks

bash
# Container health status
cfn-docker-agent-spawn health \
  --agent-id agent-frontend-001

# MCP server connectivity
cfn-docker-agent-spawn check-mcp \
  --agent-id agent-frontend-001 \
  --servers playwright,redis

Logging

bash
# Container logs
cfn-docker-agent-spawn logs \
  --agent-id agent-frontend-001 \
  --tail 100

# Structured logs for monitoring
cfn-docker-agent-spawn logs \
  --agent-id agent-frontend-001 \
  --format json \
  --output /var/log/agents/${AGENT_ID}.log

Error Handling

Container Failure Recovery

bash
# Automatic restart on failure
cfn-docker-agent-spawn \
  --agent-type ${AGENT_TYPE} \
  --restart-policy on-failure \
  --restart-count 3

# Manual recovery
cfn-docker-agent-spawn recover \
  --agent-id agent-frontend-001 \
  --backup-state

Resource Exhaustion Handling

bash
# Memory pressure handling
cfn-docker-agent-spawn \
  --memory-limit 1g \
  --memory-swap 1.5g \
  --oom-kill-disable

# CPU throttling
cfn-docker-agent-spawn \
  --cpu-limit 1.0 \
  --cpu-shares 1024

Network Isolation Issues

bash
# Network connectivity validation
cfn-docker-agent-spawn validate-network \
  --agent-id agent-frontend-001 \
  --targets redis:6379,playwright-mcp:3000

# Network repair
cfn-docker-agent-spawn repair-network \
  --agent-id agent-frontend-001 \
  --recreate-network

Performance Optimization

Startup Optimization

  • Pre-warmed Images: Use Docker image layer caching
  • Parallel Startup: Spawn multiple containers concurrently
  • Lazy Loading: Load MCP servers on-demand
  • Resource Pre-allocation: Reserve resources in advance

Memory Optimization

  • Selective MCP Loading: Only load required MCP servers
  • Workspace Cleanup: Clean temporary files automatically
  • Garbage Collection: Optimize Node.js memory management
  • Shared Libraries: Use shared mounts for common dependencies

Network Optimization

  • Local Network: Use Docker bridge networks for MCP communication
  • Connection Pooling: Reuse MCP server connections
  • DNS Caching: Cache MCP server DNS resolution
  • Compression: Compress large data transfers

Security Considerations

Container Isolation

  • Read-only Codebase: Prevent code modification
  • Limited Privileges: Run as non-root user
  • Resource Limits: Prevent DoS attacks
  • Network Segmentation: Isolate agent networks

Token Security

  • Secure Token Storage: Use tmpfs for token files
  • Token Expiration: Automatic token rotation
  • Access Logging: Log all token usage
  • Revocation: Immediate token invalidation

File System Security

  • Restricted Access: Limit file system access
  • Workspace Isolation: Isolate agent workspaces
  • Temporary Files: Secure cleanup of temporary files
  • Audit Logging: Log all file system operations

Testing and Validation

Unit Tests

  • Container creation and configuration
  • Resource limit enforcement
  • Network connectivity validation
  • Token injection and validation

Integration Tests

  • End-to-end agent spawning workflow
  • MCP server connectivity and authentication
  • Resource monitoring and alerting
  • Error handling and recovery

Performance Tests

  • Container startup time measurement
  • Resource usage benchmarking
  • Concurrent spawning scalability
  • Network performance validation

Troubleshooting

Common Issues

  1. Container Won't Start: Check image availability and resource limits
  2. MCP Connection Failed: Verify network configuration and token validity
  3. Memory Issues: Monitor usage and adjust limits
  4. Permission Errors: Check volume mounts and user permissions

Debug Commands

bash
# Debug container creation
cfn-docker-agent-spawn debug \
  --agent-type ${AGENT_TYPE} \
  --verbose \
  --dry-run

# Inspect container configuration
cfn-docker-agent-spawn inspect \
  --container-id ${CONTAINER_ID} \
  --format json

# Validate MCP connectivity
cfn-docker-agent-spawn test-mcp \
  --container-id ${CONTAINER_ID} \
  --all-servers

Best Practices

Resource Planning

  • Conservative Limits: Start with lower memory limits and increase as needed
  • Monitoring: Implement comprehensive resource monitoring
  • Capacity Planning: Plan for peak usage scenarios
  • Resource Cleanup: Clean up unused containers and volumes

Security Hardening

  • Minimal Images: Use minimal Docker images
  • Regular Updates: Keep base images updated
  • Scanning: Regularly scan images for vulnerabilities
  • Access Control: Implement proper access controls

Operational Excellence

  • Automation: Automate container lifecycle management
  • Observability: Implement comprehensive monitoring
  • Documentation: Maintain detailed configuration documentation
  • Backup: Backup critical container configurations

Didn't find tool you were looking for?

Be as detailed as possible for better results