Advanced Skill Design Patterns

Multi-step Skill Pattern

Complex tasks often need multiple steps. When designing multi-step Skills:

State Passing

• Explicit output: Require structured output (e.g., JSON) per step; next step uses it as input
• Shared context: Store intermediate state in Skill context or MCP Resources
• Checkpoints: For long flows, support resuming from a step instead of restarting

Step Description Conventions

• Each step has clear input, output, and success criteria
• Make dependencies explicit between steps (e.g., "Step 2 depends on Step 1's X field")
• Mark optional steps so the model can skip when resources are limited

Example Structure

## Step 1: Gather Information
Input: Raw user request
Output: { "keywords": [], "constraints": [] }
Success: At least one keyword extracted
Step 2: Execute Retrieval
Input: Step 1 keywords
Output: { "documents": [] }
Depends on: Step 1 complete

Conditional Branching Pattern

When the flow must branch based on intermediate results:

Branch Description

• State clearly in the Skill: "if X then A, else B"
• Use natural language like "when… then…" or "if… then…" for the model
• Provide full sub-steps for each branch to avoid model improvisation

Sub-Skill Orchestration

• Encapsulate branching in separate Skills; main Skill selects and invokes
• Implement branching via MCP Tools: Tool logic varies by parameters; Skill only passes parameters

Loops and Iteration

• Specify when to stop iterating
• Cap maximum iterations to avoid infinite loops
• Output progress per iteration for debugging and user feedback

Error Handling Pattern

Recoverable Errors

• Retry: Network timeouts, transient failures; retry with exponential backoff
• Degradation: Fall back to a simpler flow or partial result when main path fails
• Guidance: In the Skill, say "if X fails, try Y"

Unrecoverable Errors

• Clear message: Explain cause and impact in plain language
• Alternatives: Suggest manual steps or alternative approaches
• Logging: Record for analysis and improvement

Edge Cases

• Empty input, malformed input
• Insufficient permissions, unavailable resources
• Timeout and cancellation handling

Summary

Advanced Skill design needs careful attention to state passing, conditional branching, and error handling. With explicit state, clear branch descriptions, and layered error handling, you can build robust, maintainable Skills that improve execution success and user experience.