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

"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:

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)

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)

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

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

Pattern 3: Iterative Development

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

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

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:

# 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