Agent Development Workflow

Complete Standard Operating Procedure (SOP) for building production-ready goal-driven agents.

Overview

This workflow orchestrates specialized skills to take you from initial concept to production-ready agent:

•Understand Concepts → /building-agents-core (optional)
•Build Structure → /building-agents-construction
•Optimize Design → /building-agents-patterns (optional)
•Setup Credentials → /setup-credentials (if agent uses tools requiring API keys)
•Test & Validate → /testing-agent

When to Use This Workflow

Use this meta-skill when:

•Starting a new agent from scratch
•Unclear which skill to use first
•Need end-to-end guidance for agent development
•Want consistent, repeatable agent builds

Skip this workflow if:

•You only need to test an existing agent → use /testing-agent directly
•You know exactly which phase you're in → use specific skill directly

Quick Decision Tree

code

"Need to understand agent concepts" → building-agents-core
"Build a new agent" → building-agents-construction
"Optimize my agent design" → building-agents-patterns
"Set up API keys for my agent" → setup-credentials
"Test my agent" → testing-agent
"Not sure what I need" → Read phases below, then decide
"Agent has structure but needs implementation" → See agent directory STATUS.md

Phase 0: Understand Concepts (Optional)

Duration: 5-10 minutes Skill: /building-agents-core Input: Questions about agent architecture

When to Use

•First time building an agent
•Need to understand node types, edges, goals
•Want to validate tool availability
•Learning about pause/resume architecture

What This Phase Provides

•Architecture overview (Python packages, not JSON)
•Core concepts (Goal, Node, Edge, Pause/Resume)
•Tool discovery and validation procedures
•Workflow overview

Skip this phase if you already understand agent fundamentals.

Phase 1: Build Agent Structure

Duration: 15-30 minutes Skill: /building-agents-construction Input: User requirements ("Build an agent that...")

What This Phase Does

Creates the complete agent architecture:

•Package structure (exports/agent_name/)
•Goal with success criteria and constraints
•Workflow graph (nodes and edges)
•Node specifications
•CLI interface
•Documentation

Process

•Create package - Directory structure with skeleton files
•Define goal - Success criteria and constraints written to agent.py
•Design nodes - Each node approved and written incrementally
•Connect edges - Workflow graph with conditional routing
•Finalize - Agent class, exports, and documentation

Outputs

•✅ exports/agent_name/ package created
•✅ Goal defined in agent.py
•✅ 3-5 success criteria defined
•✅ 1-5 constraints defined
•✅ 5-10 nodes specified in nodes/init.py
•✅ 8-15 edges connecting workflow
•✅ Validated structure (passes python -m agent_name validate)
•✅ README.md with usage instructions
•✅ CLI commands (info, validate, run, shell)

Success Criteria

You're ready for Phase 2 when:

•Agent structure validates without errors
•All nodes and edges are defined
•CLI commands work (info, validate)
•You see: "Agent complete: exports/agent_name/"

Common Outputs

The building-agents-construction skill produces:

code

exports/agent_name/
├── __init__.py          (package exports)
├── __main__.py          (CLI interface)
├── agent.py             (goal, graph, agent class)
├── nodes/__init__.py    (node specifications)
├── config.py            (configuration)
├── implementations.py   (may be created for Python functions)
└── README.md            (documentation)

Next Steps

If structure complete and validated: → Check exports/agent_name/STATUS.md or IMPLEMENTATION_GUIDE.md → These files explain implementation options → You may need to add Python functions or MCP tools (not covered by current skills)

If want to optimize design: → Proceed to Phase 1.5 (building-agents-patterns)

If ready to test: → Proceed to Phase 2

Phase 1.5: Optimize Design (Optional)

Duration: 10-15 minutes Skill: /building-agents-patterns Input: Completed agent structure

When to Use

•Want to add pause/resume functionality
•Need error handling patterns
•Want to optimize performance
•Need examples of complex routing
•Want best practices guidance

What This Phase Provides

•Practical examples and patterns
•Pause/resume architecture
•Error handling strategies
•Anti-patterns to avoid
•Performance optimization techniques

Skip this phase if your agent design is straightforward.

Phase 2: Test & Validate

Duration: 20-40 minutes Skill: /testing-agent Input: Working agent from Phase 1

What This Phase Does

Creates comprehensive test suite:

•Constraint tests (verify hard requirements)
•Success criteria tests (measure goal achievement)
•Edge case tests (handle failures gracefully)
•Integration tests (end-to-end workflows)

Process

•Analyze agent - Read goal, constraints, success criteria
•Generate tests - Create pytest files in exports/agent_name/tests/
•User approval - Review and approve each test
•Run evaluation - Execute tests and collect results
•Debug failures - Identify and fix issues
•Iterate - Repeat until all tests pass

Outputs

•✅ Test files in exports/agent_name/tests/
•✅ Test report with pass/fail metrics
•✅ Coverage of all success criteria
•✅ Coverage of all constraints
•✅ Edge case handling verified

Success Criteria

You're done when:

•All tests pass
•All success criteria validated
•All constraints verified
•Agent handles edge cases
•Test coverage is comprehensive

Next Steps

Agent ready for:

•Production deployment
•Integration into larger systems
•Documentation and handoff
•Continuous monitoring

Phase Transitions

From Phase 1 to Phase 2

Trigger signals:

•"Agent complete: exports/..."
•Structure validation passes
•README indicates implementation complete

Before proceeding:

•Verify agent can be imported: from exports.agent_name import default_agent
•Check if implementation is needed (see STATUS.md or IMPLEMENTATION_GUIDE.md)
•Confirm agent executes without import errors

Skipping Phases

When to skip Phase 1:

•Agent structure already exists
•Only need to add tests
•Modifying existing agent

When to skip Phase 2:

•Prototyping or exploring
•Agent not production-bound
•Manual testing sufficient

Common Patterns

Pattern 1: Complete New Build (Simple)

code

User: "Build an agent that monitors files"
→ Use /building-agents-construction
→ Agent structure created
→ Use /testing-agent
→ Tests created and passing
→ Done: Production-ready agent

Pattern 1b: Complete New Build (With Learning)

code

User: "Build an agent (first time)"
→ Use /building-agents-core (understand concepts)
→ Use /building-agents-construction (build structure)
→ Use /building-agents-patterns (optimize design)
→ Use /testing-agent (validate)
→ Done: Production-ready agent

Pattern 2: Test Existing Agent

code

User: "Test my agent at exports/my_agent"
→ Skip Phase 1
→ Use /testing-agent directly
→ Tests created
→ Done: Validated agent

Pattern 3: Iterative Development

code

User: "Build an agent"
→ Use /building-agents-construction (Phase 1)
→ Implementation needed (see STATUS.md)
→ [User implements functions]
→ Use /testing-agent (Phase 2)
→ Tests reveal bugs
→ [Fix bugs manually]
→ Re-run tests
→ Done: Working agent

Pattern 4: Complex Agent with Patterns

code

User: "Build an agent with multi-turn conversations"
→ Use /building-agents-core (learn pause/resume)
→ Use /building-agents-construction (build structure)
→ Use /building-agents-patterns (implement pause/resume pattern)
→ Use /testing-agent (validate conversation flows)
→ Done: Complex conversational agent

Skill Dependencies

code

agent-workflow (meta-skill)
    │
    ├── building-agents-core (foundational)
    │   ├── Architecture concepts
    │   ├── Node/Edge/Goal definitions
    │   ├── Tool discovery procedures
    │   └── Workflow overview
    │
    ├── building-agents-construction (procedural)
    │   ├── Creates package structure
    │   ├── Defines goal
    │   ├── Adds nodes incrementally
    │   ├── Connects edges
    │   ├── Finalizes agent class
    │   └── Requires: building-agents-core
    │
    ├── building-agents-patterns (reference)
    │   ├── Best practices
    │   ├── Pause/resume patterns
    │   ├── Error handling
    │   ├── Anti-patterns
    │   └── Performance optimization
    │
    └── testing-agent
        ├── Reads agent goal
        ├── Generates tests
        ├── Runs evaluation
        └── Reports results

Troubleshooting

"Agent structure won't validate"

•Check node IDs match between nodes/init.py and agent.py
•Verify all edges reference valid node IDs
•Ensure entry_node exists in nodes list
•Run: PYTHONPATH=core:exports python -m agent_name validate

"Agent has structure but won't run"

•Check for STATUS.md or IMPLEMENTATION_GUIDE.md in agent directory
•Implementation may be needed (Python functions or MCP tools)
•This is expected - building-agents-construction creates structure, not implementation
•See implementation guide for completion options

"Tests are failing"

•Review test output for specific failures
•Check agent goal and success criteria
•Verify constraints are met
•Use /testing-agent to debug and iterate
•Fix agent code and re-run tests

"Not sure which phase I'm in"

Run these checks:

bash

# Check if agent structure exists
ls exports/my_agent/agent.py

# Check if it validates
PYTHONPATH=core:exports python -m my_agent validate

# Check if tests exist
ls exports/my_agent/tests/

# If structure exists and validates → Phase 2 (testing)
# If structure doesn't exist → Phase 1 (building)
# If tests exist but failing → Debug phase

Best Practices

For Phase 1 (Building)

•Start with clear requirements - Know what the agent should do
•Define success criteria early - Measurable goals drive design
•Keep nodes focused - One responsibility per node
•Use descriptive names - Node IDs should explain purpose
•Validate incrementally - Check structure after each major addition

For Phase 2 (Testing)

•Test constraints first - Hard requirements must pass
•Mock external dependencies - Use mock mode for LLMs/APIs
•Cover edge cases - Test failures, not just success paths
•Iterate quickly - Fix one test at a time
•Document test patterns - Future tests follow same structure

General Workflow

•Use version control - Git commit after each phase
•Document decisions - Update README with changes
•Keep iterations small - Build → Test → Fix → Repeat
•Preserve working states - Tag successful iterations
•Learn from failures - Failed tests reveal design issues

Exit Criteria

You're done with the workflow when:

✅ Agent structure validates ✅ All tests pass ✅ Success criteria met ✅ Constraints verified ✅ Documentation complete ✅ Agent ready for deployment

Additional Resources

•building-agents-core: See .claude/skills/building-agents-core/SKILL.md
•building-agents-construction: See .claude/skills/building-agents-construction/SKILL.md
•building-agents-patterns: See .claude/skills/building-agents-patterns/SKILL.md
•testing-agent: See .claude/skills/testing-agent/SKILL.md
•Agent framework docs: See core/README.md
•Example agents: See exports/ directory

Summary

This workflow provides a proven path from concept to production-ready agent:

•Learn with /building-agents-core → Understand fundamentals (optional)
•Build with /building-agents-construction → Get validated structure
•Optimize with /building-agents-patterns → Apply best practices (optional)
•Test with /testing-agent → Get verified functionality

The workflow is flexible - skip phases as needed, iterate freely, and adapt to your specific requirements. The goal is production-ready agents built with consistent, repeatable processes.

Skill Selection Guide

Choose building-agents-core when:

•First time building agents
•Need to understand architecture
•Validating tool availability
•Learning about node types and edges

Choose building-agents-construction when:

•Actually building an agent
•Have clear requirements
•Ready to write code
•Want step-by-step guidance

Choose building-agents-patterns when:

•Agent structure complete
•Need advanced patterns
•Implementing pause/resume
•Optimizing performance
•Want best practices

Choose testing-agent when:

•Agent structure complete
•Ready to validate functionality
•Need comprehensive test coverage
•Debugging agent behavior