11 KiB
11 KiB
Meta-Automation Architect
A meta-skill that analyzes your project and generates a comprehensive automation system with custom subagents, skills, commands, and hooks.
What It Creates
The meta-skill generates:
- Custom Subagents - Specialized analysis and implementation agents that run in parallel
- Skills - Auto-invoked capabilities for common patterns in your project
- Commands - Slash commands for frequent workflows
- Hooks - Event-driven automation at lifecycle points
- MCP Configurations - External service integrations
- Complete Documentation - Usage guides and quick references
How to Use
Basic Invocation
Simply describe what you want:
"Set up automation for my project"
Or be more specific:
"Create comprehensive automation for my Next.js e-commerce project"
"Generate a custom automation system for my Python data science workflow"
What Happens
-
Interactive Discovery - You'll be asked questions about:
- Project type (with smart detection and recommendations)
- Tech stack and frameworks
- Team size and workflow
- Pain points and priorities
- Desired automation scope
-
Smart Recommendations - Every question includes:
- Data-driven analysis of your project
- Confidence scores and reasoning
- Recommended options based on evidence
- Clear trade-offs and explanations
-
Multi-Agent Generation - The system creates:
- A coordinator agent that orchestrates everything
- Specialized analysis agents (security, performance, quality, etc.)
- Implementation agents (skill/command/hook generators)
- Validation agents (testing and documentation)
-
Parallel Execution - Agents run concurrently and communicate via the Agent Communication Protocol (ACP)
-
Complete Delivery - You receive:
- All automation artifacts
- Comprehensive documentation
- Usage examples
- Customization guides
Example Sessions
Web Application Project
User: "Set up automation for my React TypeScript project"
Meta-Skill:
1. Detects: Web application (95% confidence)
- Found package.json with React dependencies
- Found src/App.tsx and TypeScript config
- Detected testing with Jest and React Testing Library
2. Asks: "What are your main pain points?"
- Recommends: Testing automation (detected low test coverage)
- Recommends: Code quality checks (found 47 bug-fix commits recently)
3. Recommends: 6 agents for comprehensive coverage
- Analysis: Security, Performance, Code Quality, Dependencies
- Implementation: Skill Generator, Command Generator
- Validation: Integration Tester
4. Generates automation system with:
- /test-fix command for TDD workflow
- PostToolUse hook for auto-formatting
- GitHub MCP integration for PR automation
- Custom skills for common React patterns
Python Data Science Project
User: "Create automation for my machine learning project"
Meta-Skill:
1. Detects: Data Science (88% confidence)
- Found notebooks/ directory with 15 .ipynb files
- Found requirements.txt with pandas, scikit-learn, tensorflow
- Found data/ and models/ directories
2. Asks: "What would you like to automate first?"
- Recommends: Experiment tracking (detected many model versions)
- Recommends: Documentation generation (missing architecture docs)
- Recommends: Data validation (found data pipeline code)
3. Generates automation system with:
- /run-experiment command for standardized ML runs
- Custom skill for model comparison and analysis
- Hooks for auto-documenting experiments
- MCP integration for MLflow or Weights & Biases
Agent Communication Protocol (ACP)
The generated subagents communicate via a file-based protocol:
Directory Structure
.claude/agents/context/{session-id}/
├── coordination.json # Tracks agent status and dependencies
├── messages.jsonl # Append-only event log
├── reports/ # Standardized agent outputs
│ ├── security-analyzer.json
│ ├── performance-analyzer.json
│ └── ...
└── data/ # Shared data artifacts
├── vulnerabilities.json
├── performance-metrics.json
└── ...
How Agents Communicate
- Check Dependencies - Read
coordination.jsonto see which agents have completed - Read Context - Review reports from other agents
- Log Progress - Write events to
messages.jsonl - Share Findings - Create standardized report in
reports/ - Share Data - Store detailed artifacts in
data/ - Update Status - Mark completion in
coordination.json
Report Format
Every agent writes a standardized JSON report:
{
"agent_name": "security-analyzer",
"timestamp": "2025-01-23T10:00:00Z",
"status": "completed",
"summary": "Found 5 security vulnerabilities requiring immediate attention",
"findings": [
{
"type": "issue",
"severity": "high",
"title": "SQL Injection Risk",
"description": "User input not sanitized in query builder",
"location": "src/db/queries.ts:42",
"recommendation": "Use parameterized queries",
"example": "db.query('SELECT * FROM users WHERE id = ?', [userId])"
}
],
"metrics": {
"items_analyzed": 150,
"issues_found": 5,
"time_taken": "2m 34s"
},
"recommendations_for_automation": [
"Skill: SQL injection checker",
"Hook: Validate queries on PreToolUse",
"Command: /security-scan for quick checks"
]
}
What Gets Generated
1. Custom Subagents
Specialized agents tailored to your project:
- Analysis Agents - Security, performance, code quality, dependencies, documentation
- Implementation Agents - Generate skills, commands, hooks, MCP configs
- Validation Agents - Test integration, validate documentation
Each agent:
- Has communication protocol built-in
- Knows how to coordinate with others
- Writes standardized reports
- Suggests automation opportunities
2. Skills
Auto-invoked capabilities for your specific patterns:
.claude/skills/
├── api-doc-generator/ # Generate API docs from code
├── tdd-enforcer/ # Test-driven development workflow
├── security-checker/ # Quick security validation
└── ...
3. Commands
Slash commands for frequent tasks:
.claude/commands/
├── test-fix.md # Run tests and fix failures
├── deploy-check.md # Pre-deployment validation
├── security-scan.md # Quick security audit
└── ...
4. Hooks
Event-driven automation:
.claude/hooks/
├── format_on_save.py # PostToolUse: Auto-format code
├── security_check.py # PreToolUse: Validate operations
└── run_tests.py # Stop: Execute test suite
5. Documentation
Complete usage guides:
.claude/AUTOMATION_README.md- Main system documentation.claude/QUICK_REFERENCE.md- Cheat sheet for all features.claude/agents/context/{session-id}/- Generation session details
Monitoring the Generation Process
While agents work, you can monitor progress:
# Watch agent status
watch -n 2 'cat .claude/agents/context/*/coordination.json | jq ".agents"'
# Follow live events
tail -f .claude/agents/context/*/messages.jsonl | jq
# Check completion
cat .claude/agents/context/*/coordination.json | \
jq '.agents | to_entries | map(select(.value.status == "completed")) | map(.key)'
Customizing Generated Automation
All generated artifacts can be customized:
Modify Agents
# Edit agent behavior
vim .claude/agents/security-analyzer.md
# Adjust analysis focus, tools, or process
Customize Skills
# Update skill behavior
vim .claude/skills/api-doc-generator/SKILL.md
# Modify when skill triggers or what it does
Update Commands
# Change command behavior
vim .claude/commands/test-fix.md
# Adjust workflow or add arguments
Adjust Hooks
# Modify hook logic
vim .claude/hooks/format_on_save.py
# Change trigger conditions or actions
Troubleshooting
Agent Failed
# Check status
jq '.agents | to_entries | map(select(.value.status == "failed"))' \
.claude/agents/context/{session-id}/coordination.json
# Find error
jq 'select(.from == "failed-agent") | select(.type == "error")' \
.claude/agents/context/{session-id}/messages.jsonl | tail -1
# Options:
# 1. Retry the agent
# 2. Continue without it
# 3. Manual intervention
Missing Reports
# List generated reports
ls .claude/agents/context/{session-id}/reports/
# Check if agent completed
jq '.agents["agent-name"]' \
.claude/agents/context/{session-id}/coordination.json
Review What Happened
# Full event log
cat .claude/agents/context/{session-id}/messages.jsonl | jq
# Agent-specific events
jq 'select(.from == "agent-name")' \
.claude/agents/context/{session-id}/messages.jsonl
# Events by type
jq -s 'group_by(.type) | map({type: .[0].type, count: length})' \
.claude/agents/context/{session-id}/messages.jsonl
Advanced Usage
Specify Agent Count
"Create automation with 8 parallel agents for comprehensive coverage"
Target Specific Areas
"Focus automation on security and testing"
Prioritize Implementation
"Generate skills and commands first, hooks later"
Re-run Analysis
# Generate new session with different configuration
# Previous sessions remain in .claude/agents/context/
Architecture
The meta-skill uses a multi-phase architecture:
- Discovery Phase - Interactive questioning with recommendations
- Setup Phase - Initialize communication infrastructure
- Analysis Phase - Parallel agent execution for deep analysis
- Synthesis Phase - Coordinator reads all reports and makes decisions
- Implementation Phase - Parallel generation of automation artifacts
- Validation Phase - Sequential testing and documentation checks
- Delivery Phase - Complete documentation and user report
Benefits
- Parallel Execution - Multiple agents work concurrently
- Isolated Contexts - Each agent has focused responsibility
- Communication Protocol - Agents share findings reliably
- Data-Driven - Recommendations based on actual project analysis
- Comprehensive - Covers security, performance, quality, testing, docs
- Customizable - All generated artifacts can be modified
- Transparent - Full event log shows what happened
- Reusable - Generated automation works immediately
Support
For issues or questions:
- Review agent reports in
reports/ - Check message log in
messages.jsonl - Consult individual documentation
- Review session details in context directory
Generated automation is project-specific but follows Claude Code best practices for skills, commands, hooks, and MCP integration.