skill-forge-plan

# 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: ```markdown | 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: ```markdown # 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 ```