Skill Architecture & Design Planning

Process

Step 1: Domain Discovery

Ask the user these questions (adapt based on context):

1. What domain is this skill for? (e.g., SEO, advertising, DevOps, data analysis)
2. What are the top 2-3 use cases? What should users be able to accomplish?
3. What trigger phrases would users say? List 5-10 natural language triggers.
4. Does it need external tools? MCP servers, APIs, CLI tools?
5. Who is the target user? Developer, marketer, analyst, general user?

Step 2: Use Case Decomposition

For each use case, define:

Use Case: [Name]
Trigger: User says "[phrases]"
Steps:
1. [First action]
2. [Decision point or validation]
3. [Next action]
Result: [What success looks like]
Tools Needed: [built-in, MCP, scripts]

Step 3: Complexity Tier Assessment

Evaluate based on answers:

Signal	Tier 1	Tier 2	Tier 3	Tier 4
Use cases	1-2	2-3	4-8	8+
Needs scripts?	No	Yes	Maybe	Yes
Sub-skills needed?	No	No	Yes	Yes
Parallel execution?	No	No	No	Yes
Reference docs?	No	Maybe	Yes	Yes
Industry templates?	No	No	Maybe	Yes

Decision matrix:

• Single workflow, no scripts -> Tier 1 (minimal)
• Needs deterministic validation -> Tier 2 (workflow)
• Multiple distinct workflows -> Tier 3 (multi-skill)
• Complex domain with parallel delegation -> Tier 4 (ecosystem)

Step 4: Architecture Design

Based on tier, generate the architecture:

Tier 1 Output:

skill-name/
  SKILL.md

Tier 2 Output:

skill-name/
  SKILL.md
  scripts/
    validate.py
    process.py
  references/
    domain-knowledge.md

Tier 3 Output:

skill-name/              # Main orchestrator
  SKILL.md
  references/
    shared-reference.md
skills/
  skill-name-sub1/
    SKILL.md
  skill-name-sub2/
    SKILL.md

Tier 4 Output:

skill-name/              # Main orchestrator
  SKILL.md
  references/
    ref1.md
    ref2.md
  scripts/
    script1.py
    script2.py
  assets/
    template1.md
    template2.md
skills/
  skill-name-sub1/
    SKILL.md
  skill-name-sub2/
    SKILL.md
  ...
agents/
  skill-name-role1.md
  skill-name-role2.md

Step 5: Sub-Skill Decomposition (Tier 3-4 only)

For each sub-skill, define:

• Name: {parent}-{function} (kebab-case)
• Responsibility: Single, clear purpose
• Inputs: What it needs from the orchestrator
• Outputs: What it returns
• Cross-references: Other sub-skills or references it needs
• Self-contained?: Can it run independently or needs orchestration?

Step 6: Routing Table

Design the command routing:

| Command | Routes to | Purpose |
|---------|-----------|---------|
| /skill-name | main SKILL.md | Interactive mode |
| /skill-name sub1 | skills/skill-name-sub1/ | Sub-workflow 1 |
| /skill-name sub2 | skills/skill-name-sub2/ | Sub-workflow 2 |

Step 7: Reference File Planning

Identify knowledge that should be extracted to reference files:

• Domain-specific rules and thresholds
• Industry templates
• API documentation
• Quality gates and validation criteria

Rule of thumb: If information is >50 lines and only needed for specific sub-workflows, extract it to references/.

Step 8: Generate Plan Document

Create a structured plan document:

# Skill Plan: [name]

## Overview
- Domain: [domain]
- Tier: [1-4]
- Sub-skills: [count]
- Scripts: [count]

## Use Cases
[list from Step 2]

## Architecture
[diagram from Step 4]

## Sub-Skills
[details from Step 5]

## Routing
[table from Step 6]

## Reference Files
[list from Step 7]

## Next Steps
Run `/skill-forge build [name]` to scaffold the skill.

Examples

Example: Planning a DevOps Skill

User: "I want to create a skill for managing Docker containers and Kubernetes deployments"

Discovery reveals:

• 6 use cases (container management, K8s deploy, monitoring, logs, scaling, troubleshooting)
• Needs scripts for kubectl and docker commands
• Multiple distinct workflows
• Cross-references between monitoring and troubleshooting

Assessment: Tier 3 (multi-skill orchestrator)

Architecture:

devops/                     # Main orchestrator
  SKILL.md
  scripts/
    health_check.py         # Cluster health check
    log_parser.py           # Log analysis
  references/
    k8s-patterns.md         # Deployment patterns
    docker-best-practices.md
skills/
  devops-docker/SKILL.md  # Container management
  devops-k8s/SKILL.md     # Kubernetes deployments
  devops-monitor/SKILL.md # Monitoring and alerts
  devops-logs/SKILL.md    # Log analysis
  devops-scale/SKILL.md   # Scaling strategies
  devops-fix/SKILL.md     # Troubleshooting