76 lines
2.7 KiB
Markdown
76 lines
2.7 KiB
Markdown
# Skill Design Patterns
|
|
|
|
Five proven patterns for structuring skills. Choose based on workflow type.
|
|
|
|
## Choosing Approach: Problem-First vs Tool-First
|
|
|
|
- **Problem-first:** "I need to set up a project workspace" → skill orchestrates the right calls in sequence. Users describe outcomes; skill handles tools.
|
|
- **Tool-first:** "I have Notion MCP connected" → skill teaches optimal workflows and best practices. Users have access; skill provides expertise.
|
|
|
|
## Pattern 1: Sequential Workflow Orchestration
|
|
|
|
**Use when:** Multi-step processes must happen in specific order.
|
|
|
|
**Key techniques:**
|
|
- Explicit step ordering with dependencies
|
|
- Validation at each stage
|
|
- Rollback instructions for failures
|
|
|
|
```markdown
|
|
## Workflow: Onboard New Customer
|
|
### Step 1: Create Account
|
|
Call MCP tool: `create_customer` → Parameters: name, email, company
|
|
### Step 2: Setup Payment
|
|
Call MCP tool: `setup_payment_method` → Wait for verification
|
|
### Step 3: Create Subscription
|
|
Call MCP tool: `create_subscription` → Uses customer_id from Step 1
|
|
```
|
|
|
|
## Pattern 2: Multi-MCP Coordination
|
|
|
|
**Use when:** Workflows span multiple services (Figma → Drive → Linear → Slack).
|
|
|
|
**Key techniques:**
|
|
- Clear phase separation
|
|
- Data passing between MCPs
|
|
- Validation before moving to next phase
|
|
- Centralized error handling
|
|
|
|
## Pattern 3: Iterative Refinement
|
|
|
|
**Use when:** Output quality improves with iteration (reports, documents).
|
|
|
|
**Key techniques:**
|
|
- Generate initial draft → validate with script → refine → re-validate
|
|
- Explicit quality criteria and "stop iterating" conditions
|
|
- Bundled validation scripts for deterministic checks
|
|
|
|
## Pattern 4: Context-Aware Tool Selection
|
|
|
|
**Use when:** Same outcome, different tools depending on context.
|
|
|
|
**Key techniques:**
|
|
- Decision tree based on inputs (file type, size, destination)
|
|
- Fallback options when primary tool unavailable
|
|
- Transparency about why a tool was chosen
|
|
|
|
## Pattern 5: Domain-Specific Intelligence
|
|
|
|
**Use when:** Skill adds specialized knowledge beyond tool access (compliance, finance).
|
|
|
|
**Key techniques:**
|
|
- Domain rules embedded in logic (compliance checks before action)
|
|
- Comprehensive audit trails
|
|
- Clear governance and documentation of decisions
|
|
|
|
## Use Case Categories
|
|
|
|
### Category 1: Document & Asset Creation
|
|
Creates consistent output (documents, presentations, apps, designs). Uses embedded style guides, templates, quality checklists. No external tools required.
|
|
|
|
### Category 2: Workflow Automation
|
|
Multi-step processes with consistent methodology. Uses step-by-step workflows with validation gates, templates, iterative refinement loops.
|
|
|
|
### Category 3: MCP Enhancement
|
|
Workflow guidance atop MCP tool access. Coordinates multiple MCP calls, embeds domain expertise, handles common MCP errors.
|