Skillflows

Skillflows are tracked, discoverable, evolvable workflows that AI agents can execute. Unlike simple markdown prompts, skillflows have:

• Discoverability - Agents can search for relevant workflows
• Executability - Structured steps with error handling
• Trackability - Execution history and success rates
• Evolvability - Refined based on outcomes

Lifecycle

Create → Discover → Execute → Complete → Refine → Deprecate

MCP Tools

Tool	Purpose
mcpammer_skillflow_create	Create new skillflow
mcpammer_skillflow_get	Get by ID or name
mcpammer_skillflow_list	List with optional filters
mcpammer_skillflow_search	Full-text search
mcpammer_skillflow_execute	Start execution
mcpammer_skillflow_execution_complete	Mark execution done
mcpammer_skillflow_update	Update definition
mcpammer_skillflow_executions_list	View execution history

Creating a Skillflow

await skillflows.create(
    name='my-workflow',           # Unique slug (kebab-case)
    title='My Workflow',          # Human-readable name
    description='What it does...',
    status='active',              # draft | active | deprecated
    tags=['automation'],
    inputs=[
        {"name": "param1", "type": "string", "required": True, "description": "..."}
    ],
    outputs=[
        {"name": "result", "type": "string", "description": "..."}
    ],
    preconditions=["Requirement 1", "Requirement 2"],
    steps=[
        {"order": 1, "action": "tool_name", "description": "...", "on_error": "abort"},
        {"order": 2, "action": "tool_name", "description": "...", "outputs": ["var"], "on_error": "warn"}
    ]
)

Executing a Skillflow

# Start execution
result = await skillflows.execute('my-workflow', inputs={'param1': 'value'})
execution_id = result['execution_id']
steps = result['skillflow']['steps']

# Execute steps...

# Complete execution
await skillflows.execution_complete(
    execution_id=execution_id,
    status='completed',  # completed | failed | cancelled
    step_results=[...],
    outputs={'result': 'value'}
)

Step Definition

{
  "order": 1,
  "action": "mcpammer_tool_name",
  "description": "What this step does",
  "inputs": {"param": "{variable}"},
  "outputs": ["captured_var"],
  "on_error": "abort"  // abort | warn | retry | skip
}

Built-in Skillflows

Name	Purpose
deploy-new-service	Full service deployment pipeline
claim-ready-work	Find and claim next ticket
daily-healthcheck	System-wide health check
ralph-loop	Iterative AI development loop

Metrics

The v_skillflows view includes execution metrics:

• execution_count - Total executions
• completed_count - Successful completions
• failed_count - Failed executions
• success_rate - Percentage (0-100)
• avg_duration_ms - Average execution time

Best Practices

1. Clear completion criteria - Define what "done" means
2. Atomic steps - Each step should do one thing
3. Error handling - Choose appropriate on_error behavior
4. Version tracking - Version auto-increments on content changes
5. Tags for discovery - Use meaningful tags for search