adaptationio/planning-architect

Planning Architect

Overview

planning-architect systematically plans Claude Code skill development from initial concept to detailed implementation blueprint. It guides you through six sequential steps to create comprehensive skill plans that ensure successful development.

Purpose: Transform skill ideas into actionable implementation plans with clear structure, accurate estimates, and identified dependencies.

Value: Prevents rework, reduces development time, ensures consistency, and produces better-designed skills through systematic planning.

When to Use:

• Planning new skills from scratch
• Converting existing documentation into skills
• Architecting complex multi-file skills
• Planning skill improvements or refactoring
• Coordinating dependent skill development

Prerequisites

Before planning a skill, gather:

1. Problem Definition: Clear understanding of what problem the skill solves
2. Domain Knowledge: Familiarity with the domain being captured
3. User Context: Understanding of who will use the skill and how
4. Existing Resources: Any documentation, examples, or patterns to reference
5. Skill-Builder Context: Familiarity with skill-builder-generic patterns

Planning Workflow

Step 1: Analyze Requirements

Objective: Clearly define what the skill must accomplish and its scope

Process:

1. Define the Problem

   • What specific problem does this skill solve?
   • What pain point does it address?
   • What would happen without this skill?

2. Identify Target Users

   • Who will use this skill? (You, team, community)
   • What is their expertise level?
   • What context will they invoke it in?

3. Capture Domain Knowledge

   • What domain expertise must be captured?
   • What workflows need documentation?
   • What best practices should be included?
   • What anti-patterns should be avoided?

4. Determine Scope

   • What is explicitly in scope?
   • What is explicitly out of scope?
   • What are the boundaries?
   • What is the minimum viable skill?

5. Identify Existing Resources

   • Are there similar skills to reference?
   • Is there existing documentation to convert?
   • Are there community patterns to follow?
   • Are there anti-patterns to avoid?

Questions to Answer:

Problem Definition:
- What problem does this skill solve?
- Who experiences this problem?
- How do they currently solve it (if at all)?
- What would success look like?

Scope:
- What is the primary objective?
- What are secondary objectives?
- What is explicitly out of scope?
- What is the minimum viable version?

Users:
- Who will use this skill?
- What is their expertise level?
- What context will they invoke it in?
- What other skills do they likely have?

Domain:
- What domain knowledge is required?
- What workflows exist in this domain?
- What terminology is standard?
- What are common pitfalls?

Resources:
- Are there similar skills to study?
- Is there documentation to convert?
- Are there examples to follow?
- What research is needed?

Output: Requirements document answering all questions above

Example:

Problem: Developers waste time debugging Railway deployments
Users: Development team with Node.js experience
Domain: Railway deployment, Docker, environment config
Scope: Railway-specific deployment workflow for Node.js + React
Out of Scope: Other platforms (Vercel, AWS), other languages
Resources: Railway docs, existing deployment notes
MVP: Basic deployment workflow with common troubleshooting

See Also: references/pattern-selection-guide.md includes requirements analysis templates

---

Step 2: Select Organizational Pattern

Objective: Choose the optimal organizational pattern for this skill

The 4 Organizational Patterns:

Pattern 1: Workflow-Based

Use When: Sequential processes with clear steps where order matters

Characteristics:

• Linear progression (Step 1 → Step 2 → Step 3)
• Each step builds on previous steps
• Clear start and end points
• Dependencies between steps

Examples:

• Deployment workflows
• API integration processes
• Testing workflows
• Setup/configuration sequences

Structure:

## Workflow
### Step 1: [Action]
### Step 2: [Action]
### Step 3: [Action]

Choose This When:

• Process has clear sequential steps
• Order of operations matters
• Steps have dependencies
• There's a defined goal at the end

---

Pattern 2: Task-Based

Use When: Independent operations without order dependency

Characteristics:

• Tasks can be performed in any order
• No dependencies between tasks
• Quick reference format
• Each task is self-contained

Examples:

• Troubleshooting guides
• Utility collections
• Command references
• Independent operations

Structure:

## Tasks
### Task A: [Action]
### Task B: [Action]
### Task C: [Action]

Choose This When:

• Operations are independent
• Order doesn't matter
• Users will perform subset of tasks
• Quick lookup is primary use case

---

Pattern 3: Reference/Guidelines

Use When: Standards, patterns, design systems, best practices

Characteristics:

• Reference material (look-up)
• Guidelines and standards
• Comprehensive coverage
• Examples and specifications

Examples:

• Design systems
• Coding standards
• API documentation
• Style guides

Structure:

## Guidelines
### Guideline 1: [Concept]
### Guideline 2: [Concept]

## Reference
### Component A
### Component B

Choose This When:

• Documenting standards or patterns
• Creating reference material
• Establishing guidelines
• Comprehensive coverage needed

---

Pattern 4: Capabilities-Based

Use When: Integrated feature suites with multiple entry points

Characteristics:

• Multiple interconnected features
• Various entry points
• Features work together
• Complex integrations

Examples:

• Complex systems
• Platforms with multiple features
• Toolkits with related capabilities

Structure:

## Capabilities
### Capability A: [Feature]
### Capability B: [Feature]

## Integration
How capabilities work together

Choose This When:

• Multiple related features
• Features can be used independently or together
• Multiple valid starting points
• Complex system with many capabilities

---

Decision Process:

START
↓
Does the skill describe a sequential process?
├─ YES → Is order important?
│         ├─ YES → WORKFLOW-BASED
│         └─ NO → TASK-BASED
│
└─ NO → Is it primarily reference material?
         ├─ YES → REFERENCE/GUIDELINES
         └─ NO → Does it have multiple integrated features?
                  ├─ YES → CAPABILITIES-BASED
                  └─ NO → Re-examine requirements (likely TASK-BASED)

Pattern Selection Factors:

| Factor | Workflow | Task | Reference | Capabilities | |--------|----------|------|-----------|--------------| | Order matters | ✓ | ✗ | ✗ | ~ | | Dependencies | ✓ | ✗ | ✗ | ✓ | | Quick lookup | ✗ | ✓ | ✓ | ~ | | Sequential process | ✓ | ✗ | ✗ | ~ | | Standards/guidelines | ✗ | ✗ | ✓ | ✗ | | Multiple features | ~ | ✗ | ✗ | ✓ | | Integration complexity | ~ | ✗ | ✗ | ✓ |

Output: Selected organizational pattern with justification

Example:

Pattern: Workflow-Based
Justification: Railway deployment is sequential (prepare → configure → deploy → verify)
Alternative Considered: Task-based rejected because order matters

See Also: references/pattern-selection-guide.md for comprehensive decision tree and examples

---

Step 3: Plan File Structure

Objective: Define complete file structure using progressive disclosure

Progressive Disclosure Architecture:

The key principle: Keep SKILL.md lean, bundle details in references/

Three-Level System:

1. SKILL.md (Always Loaded)

   • Target: <5,000 words (~1,000-1,500 lines)
   • Content: Overview, quick start, key workflows, core concepts
   • Purpose: Provides essential context without overwhelming Claude's context window

2. references/ (Loaded On-Demand)

   • Target: 10,000+ words okay per file
   • Content: Comprehensive guides, detailed explanations, extensive examples
   • Purpose: Deep details available when needed without bloating main skill

3. scripts/ (Loaded When Executed)

   • Target: Any size
   • Content: Automation helpers, validation tools, generators
   • Purpose: Executable tools that extend skill capabilities

4. templates/ (Loaded When Needed)

   • Target: Any size
   • Content: Reusable patterns, boilerplate code, scaffolds
   • Purpose: Starting points for common patterns

File Structure Planning:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter
│   ├── Overview
│   ├── Prerequisites (if needed)
│   ├── Main content (workflow/tasks/guidelines/capabilities)
│   ├── Quick Start
│   ├── Examples (brief)
│   └── References (links to references/)
│
├── references/ (optional but recommended)
│   ├── detailed-guide-1.md (comprehensive guide)
│   ├── detailed-guide-2.md (another detailed guide)
│   └── advanced-topics.md (deep dive content)
│
├── scripts/ (optional)
│   ├── helper-script.py (automation)
│   └── validation-script.py (validation)
│
└── templates/ (optional)
    ├── template-1.md (reusable pattern)
    └── template-2.md (another pattern)

SKILL.md Content Allocation:

Include in SKILL.md:

• Problem overview (why skill exists)
• Prerequisites
• Core workflow/tasks/guidelines/capabilities
• Quick start instructions
• Brief examples (1-3)
• Links to references for details

Move to references/:

• Comprehensive step-by-step guides
• Extensive examples (4+)
• Detailed explanations
• Advanced topics
• Troubleshooting guides
• Deep dives into concepts
• Long reference tables

Move to scripts/:

• Automation helpers
• Validation tools
• Code generators
• Analysis tools
• Interactive wizards

Move to templates/:

• Boilerplate files
• Configuration templates
• Code scaffolds
• Reusable patterns

Reference File Naming:

Use descriptive hyphen-case names:

• pattern-selection-guide.md (not guide1.md)
• complexity-estimation-techniques.md (not complexity.md)
• advanced-workflows.md (not advanced.md)

Reference Organization Strategies:

1. By Topic (Most Common)

   references/
   ├── authentication-guide.md
   ├── data-fetching-guide.md
   └── error-handling-guide.md
   

2. By Depth (Progressive Learning)

   references/
   ├── basics-guide.md
   ├── intermediate-guide.md
   └── advanced-guide.md
   

3. By Workflow Step (For Workflow-Based)

   references/
   ├── step1-preparation-guide.md
   ├── step2-execution-guide.md
   └── step3-validation-guide.md
   

4. By Use Case (For Task-Based)

   references/
   ├── use-case-api-integration.md
   ├── use-case-database-setup.md
   └── use-case-testing.md
   

Linking to References:

Always use relative paths with descriptive link text:

Good:
See [Pattern Selection Guide](references/pattern-selection-guide.md) for detailed decision tree.

Bad:
See references/pattern-selection-guide.md for details.

Output: Complete file structure plan with file names and content allocation

Example:

railway-deployment/
├── SKILL.md (~1,200 lines)
│   - Overview of Railway deployment
│   - Prerequisites
│   - 4-step deployment workflow
│   - Quick start example
│   - Links to references
│
├── references/
│   ├── environment-configuration-guide.md (~800 lines)
│   ├── docker-setup-guide.md (~600 lines)
│   ├── troubleshooting-common-issues.md (~1,000 lines)
│   └── railway-pricing-optimization.md (~400 lines)
│
├── scripts/
│   └── validate-config.py (~150 lines)
│
└── templates/
    └── railway-config-template.json (~50 lines)

See Also: references/structure-planning-guide.md for comprehensive progressive disclosure planning

---

Step 4: Estimate Complexity

Objective: Estimate development time and effort required

Complexity Factors:

1. Skill Size

   • Minimal (SKILL.md only): 2-4 hours
   • Small (SKILL.md + 1-2 references): 6-10 hours
   • Medium (SKILL.md + 3-5 references): 12-18 hours
   • Large (SKILL.md + 6+ references + scripts): 20-30 hours
   • Very Large (Multiple scripts, templates, extensive docs): 30+ hours

2. Pattern Complexity

   • Workflow-based: Medium (need to document each step clearly)
   • Task-based: Low-Medium (independent tasks easier to document)
   • Reference/Guidelines: Medium-High (requires comprehensive coverage)
   • Capabilities-based: High (complex interactions to document)

3. Domain Complexity

   • Familiar domain: 1x multiplier
   • Some learning needed: 1.5x multiplier
   • Significant research needed: 2x multiplier
   • Novel/complex domain: 2.5x+ multiplier

4. Automation Requirements

   • No scripts: 0 additional hours
   • Simple scripts (1-2): +4-6 hours
   • Complex scripts (3+): +10-15 hours
   • Interactive tools: +15-20 hours

5. Research Requirements

   • Existing documentation: 1x
   • Some research needed: +2-4 hours
   • Extensive research: +8-12 hours
   • No existing resources: +15+ hours

Estimation Formula:

Base Time = Skill Size (from factor 1)
Pattern Multiplier = Factor 2
Domain Multiplier = Factor 3
Automation Add = Factor 4
Research Add = Factor 5

Total Estimate = (Base Time × Pattern Multiplier × Domain Multiplier) + Automation Add + Research Add

Estimation Examples:

Example 1: Simple Troubleshooting Skill

Base: Small (6-10h) = 8h
Pattern: Task-based (1x)
Domain: Familiar (1x)
Automation: None (0h)
Research: Existing docs (0h)

Total: 8h × 1 × 1 + 0 + 0 = 8 hours

Example 2: Complex Deployment Workflow

Base: Large (20-30h) = 25h
Pattern: Workflow-based (1.2x)
Domain: Some learning (1.5x)
Automation: Simple scripts (5h)
Research: Some needed (3h)

Total: 25h × 1.2 × 1.5 + 5 + 3 = 53 hours

Example 3: Design System Reference

Base: Medium (12-18h) = 15h
Pattern: Reference/Guidelines (1.3x)
Domain: Familiar (1x)
Automation: None (0h)
Research: Existing docs (0h)

Total: 15h × 1.3 × 1 + 0 + 0 = 19.5 hours

Estimation Checklist:

• [ ] Counted number of reference files needed
• [ ] Assessed domain knowledge gap
• [ ] Identified automation needs
• [ ] Determined research requirements
• [ ] Applied pattern complexity multiplier
• [ ] Added buffer for iteration (10-20%)
• [ ] Validated estimate seems reasonable

Output: Time estimate with breakdown by component

Example:

Estimated Development Time: 42-48 hours

Breakdown:
- SKILL.md: 8 hours
- references/ (4 files): 20 hours
  - pattern-selection-guide.md: 6h
  - structure-planning-guide.md: 6h
  - complexity-estimation-guide.md: 4h
  - dependency-analysis-guide.md: 4h
- scripts/plan-skill.py: 10 hours
- templates/: 2 hours
- Validation & testing: 4 hours

Total: 44 hours (42-48 hour range)

See Also: references/complexity-estimation-guide.md for detailed estimation techniques and calibration data

---

Step 5: Identify Dependencies

Objective: Identify what this skill depends on and what depends on it

Dependency Types:

1. Skill Dependencies

Skills this skill relies on or references

Identification Questions:

• Does this skill assume other skills exist?
• Does this skill reference other skills in examples?
• Would this skill be more effective with other skills available?

Example:

planning-architect depends on:
- skill-builder-generic (for skill patterns)
- No hard dependencies, but enhanced by:
  - task-development (for breaking down implementation)
  - complexity-estimation (for time estimates)

2. Tool Dependencies

External tools or MCPs this skill requires

Identification Questions:

• Does this skill use specific Claude Code tools? (WebSearch, WebFetch, Bash, etc.)
• Does this skill require MCPs? (Context7, GitHub, etc.)
• Are there external services needed? (APIs, databases, etc.)

Example:

skill-researcher depends on:
- WebSearch tool (for latest patterns)
- WebFetch tool (for documentation)
- Context7 MCP (optional, for deep context)
- GitHub API (for community skill analysis)

3. Knowledge Dependencies

Domain knowledge or prerequisites users must have

Identification Questions:

• What knowledge must users have before using this skill?
• What terminology must users understand?
• What concepts are assumed as known?

Example:

railway-deployment requires users know:
- Basic Node.js and npm
- Git basics
- Command line usage
- HTTP concepts (for API deployments)

4. File Dependencies

Files in the project this skill references

Identification Questions:

• Does this skill reference specific file paths?
• Does it assume certain project structure?
• Does it expect configuration files to exist?

Example:

deployment-guide assumes:
- package.json exists
- .env.example exists (for environment variables)
- Dockerfile exists (or provides template)

5. Reverse Dependencies (What Depends On This)

Other skills that will depend on this skill

Identification Questions:

• What skills will be built after this one?
• What skills might reference this skill?
• Who is the downstream consumer?

Example:

planning-architect will be depended on by:
- task-development (uses planning output)
- skill-researcher (feeds into planning)
- All future skill development (planning is first step)

Dependency Documentation Format:

## Dependencies

### Required
- skill-builder-generic: Core patterns and templates
- WebSearch tool: For researching similar skills

### Optional
- Context7 MCP: Enhanced context for complex planning
- skill-researcher: For comprehensive research phase

### User Prerequisites
- Familiarity with skill-builder-generic
- Understanding of progressive disclosure
- Basic markdown knowledge

### Reverse Dependencies
- task-development (will use planning output)
- skill-composer (for multi-skill workflows)

Output: Complete dependency list with all five types

Example:

Dependencies for planning-architect:

Skill Dependencies:
- Required: skill-builder-generic
- Optional: skill-researcher, analysis

Tool Dependencies:
- None (uses only standard Claude Code capabilities)

Knowledge Dependencies:
- Familiarity with Claude Code skills
- Understanding of progressive disclosure
- Markdown knowledge

File Dependencies:
- skill-builder-package/examples/* (for reference examples)

Reverse Dependencies:
- task-development (next in bootstrap sequence)
- todo-management (uses planning structure)
- All future skills (planning is foundation)

See Also: references/dependency-analysis-guide.md for dependency mapping techniques

---

Step 6: Define Validation Criteria

Objective: Establish how to validate the skill works correctly

Validation Categories:

1. Structure Validation

Does the skill have correct file structure?

Criteria:

• [ ] SKILL.md exists with valid YAML frontmatter
• [ ] Directory structure matches plan
• [ ] All reference files exist
• [ ] All scripts are executable
• [ ] All templates are present

Validation Method: Run validate-skill.py script

---

2. Content Validation

Is the content complete and correct?

Criteria:

• [ ] Overview clearly states purpose
• [ ] Prerequisites are documented
• [ ] Main content follows chosen pattern
• [ ] Examples are provided
• [ ] References are linked correctly
• [ ] Writing uses imperative voice
• [ ] No TODO placeholders (except in templates)
• [ ] Trigger keywords present in description

Validation Method: Manual review + automated checks

---

3. Functional Validation

Does the skill actually work?

Criteria:

• [ ] Can invoke skill by name
• [ ] Skill loads without errors
• [ ] References load when requested
• [ ] Scripts execute successfully
• [ ] Templates can be used
• [ ] Examples produce expected results

Validation Method: Test invocation + script execution

---

4. Usability Validation

Is the skill easy to use?

Criteria:

• [ ] Quick start is actually quick (<5 min)
• [ ] Examples are clear and relevant
• [ ] Instructions are unambiguous
• [ ] Terminology is consistent
• [ ] Navigation is intuitive
• [ ] Context window impact is minimal

Validation Method: User testing + feedback

---

5. Completeness Validation

Does the skill cover everything it should?

Criteria:

• [ ] All requirements from Step 1 are addressed
• [ ] All workflows are documented
• [ ] Edge cases are covered
• [ ] Troubleshooting is included
• [ ] Best practices are captured
• [ ] Anti-patterns are noted

Validation Method: Requirements traceability matrix

---

Validation Plan Template:

## Validation Plan

### Structure Validation
Method: Automated script
Tool: validate-skill.py
Pass Criteria: Zero errors, max 1 warning

### Content Validation
Method: Manual review
Checklist: 50-point validation checklist
Pass Criteria: All checklist items pass

### Functional Validation
Method: Test invocation
Test Cases:
1. Invoke skill in clean session
2. Request reference file
3. Execute scripts with test input
4. Use templates in sample project
Pass Criteria: All test cases succeed

### Usability Validation
Method: User testing
Testers: 2-3 developers
Pass Criteria: Users can complete quick start in <5 min

### Completeness Validation
Method: Requirements review
Process: Check each requirement has corresponding content
Pass Criteria: 100% requirements coverage

Output: Comprehensive validation plan with test cases

Example:

Validation Plan for planning-architect:

Structure:
- Run validate-skill.py
- Verify 4 reference files present
- Verify plan-skill.py is executable

Content:
- Review all 6 workflow steps
- Verify examples in each step
- Check imperative voice usage
- Validate trigger keywords

Functional:
- Invoke planning-architect
- Follow workflow for test skill
- Run plan-skill.py with test input
- Verify generates complete plan

Usability:
- Ask developer to plan simple skill
- Time quick start completion
- Gather feedback on clarity

Completeness:
- Verify all planning aspects covered
- Check all 4 patterns documented
- Ensure estimation methods present
- Validate dependency analysis included

---

Quick Start: Plan a Skill in 30 Minutes

1. Analyze Requirements (10 minutes)

Answer these questions:

• Problem: What problem does this skill solve?
• Users: Who will use it?
• Domain: What knowledge to capture?
• Scope: What's in/out of scope?

2. Select Pattern (5 minutes)

Use decision tree:

• Sequential process with dependencies? → Workflow-based
• Independent operations? → Task-based
• Standards/reference? → Reference/Guidelines
• Multiple integrated features? → Capabilities-based

3. Plan Structure (5 minutes)

skill-name/
├── SKILL.md (always)
├── references/ (if detailed guides needed)
├── scripts/ (if automation needed)
└── templates/ (if reusable patterns needed)

4. Estimate Time (5 minutes)

• Count reference files: ____
• Automation needed?: ____
• Research required?: ____
• Rough estimate: ____ hours

5. List Dependencies (3 minutes)

• Skill dependencies: ____
• Tool dependencies: ____
• Knowledge prerequisites: ____

6. Define Validation (2 minutes)

• Structure: validate-skill.py
• Functional: Test invoke + scripts
• Complete: Requirements coverage

Result: Complete plan ready for implementation!

---

Examples

Example 1: Simple Troubleshooting Skill

Requirements:

• Problem: Railway deployment errors are cryptic
• Users: Dev team with Railway experience
• Domain: Railway troubleshooting
• Scope: Common errors + solutions

Pattern: Task-based (independent error cases)

Structure:

railway-troubleshooting/
├── SKILL.md (task-based format)
└── references/
    └── advanced-troubleshooting.md

Estimate: 8-10 hours (small, familiar domain)

Dependencies:

• Knowledge: Basic Railway concepts
• No skill dependencies

Validation: Test each troubleshooting case

---

Example 2: Complex API Integration

Requirements:

• Problem: FHIR API integration is complex
• Users: Medical dev team
• Domain: FHIR, OAuth, REST
• Scope: Complete integration workflow

Pattern: Workflow-based (sequential integration steps)

Structure:

fhir-integration/
├── SKILL.md (workflow format)
├── references/
│   ├── fhir-resources-guide.md
│   ├── oauth-setup-guide.md
│   └── error-handling-guide.md
├── scripts/
│   └── validate-fhir-response.py
└── templates/
    └── fhir-request-template.json

Estimate: 35-40 hours (large, some research needed)

Dependencies:

• Skill: oauth-integration
• Tool: WebFetch (for API testing)
• Knowledge: REST APIs, JSON

Validation: Full integration test with FHIR server

---

Example 3: Design System Reference

Requirements:

• Problem: Inconsistent UI components
• Users: Frontend team
• Domain: Design system
• Scope: Colors, typography, components

Pattern: Reference/Guidelines (design standards)

Structure:

design-system/
├── SKILL.md (reference format)
├── references/
│   ├── color-palette-guide.md
│   ├── typography-guide.md
│   └── component-library.md
└── assets/
    ├── colors.png
    └── typography-examples.png

Estimate: 18-22 hours (medium, design domain)

Dependencies:

• Knowledge: Design principles, CSS
• No skill dependencies

Validation: Apply design system to sample component

---

Planning Output

After completing the 6-step workflow, you should have:

1. Requirements Document

   • Problem statement
   • User profile
   • Domain knowledge scope
   • Explicit scope boundaries
   • Resource inventory

2. Pattern Selection

   • Chosen pattern with justification
   • Rejected patterns with reasons

3. File Structure Plan

   • Complete directory tree
   • File names for all files
   • Content allocation (what goes where)
   • Progressive disclosure strategy

4. Time Estimate

   • Overall estimate with range
   • Breakdown by component
   • Complexity factors applied
   • Buffer included

5. Dependency Map

   • Skill dependencies (required + optional)
   • Tool dependencies
   • Knowledge prerequisites
   • Reverse dependencies

6. Validation Plan

   • Structure validation method
   • Content validation checklist
   • Functional test cases
   • Usability testing approach
   • Completeness criteria

Format: See templates/skill-plan-template.md for structured output format

---

Best Practices

Planning Best Practices

1. Start with Why

   • Clearly articulate the problem
   • Validate the need before planning
   • Consider if skill is the right solution

2. Choose Pattern Carefully

   • Pattern drives entire structure
   • Consider user mental model
   • Validate pattern with examples

3. Plan for Evolution

   • Skills will grow over time
   • Structure should accommodate additions
   • Leave room for future enhancements

4. Optimize Context Usage

   • Keep SKILL.md lean
   • Move details to references
   • Every word costs context tokens

5. Validate Early

   • Review plan before implementation
   • Get feedback from potential users
   • Adjust based on feedback

Common Planning Mistakes

1. Scope Creep

   • Problem: Planning too much at once
   • Solution: Define MVP, plan iterations

2. Wrong Pattern

   • Problem: Choosing workflow for independent tasks
   • Solution: Use decision tree carefully

3. Poor Progressive Disclosure

   • Problem: Putting everything in SKILL.md
   • Solution: Follow <5,000 word guideline

4. Underestimating Complexity

   • Problem: Unrealistic time estimates
   • Solution: Use formula, add buffer

5. Ignoring Dependencies

   • Problem: Missing prerequisite skills
   • Solution: Complete dependency analysis

---

References

Comprehensive guides for each planning step:

• Pattern Selection Guide - Complete decision tree with detailed examples for choosing between workflow, task, reference, and capabilities patterns. Includes edge cases and combination patterns.

• Structure Planning Guide - Deep dive into progressive disclosure, file organization strategies, content allocation techniques, and context optimization methods.

• Complexity Estimation Guide - Detailed estimation techniques, calibration data from real skills, estimation worksheets, and accuracy improvement methods.

• Dependency Analysis Guide - Comprehensive dependency identification techniques, dependency mapping strategies, circular dependency resolution, and version management.

---

Automation

Use the planning automation script for guided planning:

# Interactive planning wizard
python scripts/plan-skill.py --interactive

# Plan from description file
python scripts/plan-skill.py --description skill-description.txt

# Generate plan with specific pattern
python scripts/plan-skill.py --pattern workflow --name my-skill

# Output plan to file
python scripts/plan-skill.py --interactive --output skill-plan.md

See script help for all options:

python scripts/plan-skill.py --help

---

Success Criteria

A successful skill plan includes:

✅ Clear Requirements

• Problem clearly stated
• Users identified
• Scope explicitly defined
• Resources inventoried

✅ Justified Pattern Selection

• Pattern chosen with clear reasoning
• Alternatives considered and rejected
• Pattern fits user mental model

✅ Complete Structure Plan

• All files identified
• Content allocated appropriately
• Progressive disclosure optimized
• Naming follows conventions

✅ Realistic Estimate

• Breakdown by component
• Complexity factors applied
• Range provided (not single number)
• Buffer included

✅ Comprehensive Dependencies

• All dependency types covered
• Prerequisites documented
• Reverse dependencies identified

✅ Validation Strategy

• Multiple validation types
• Clear pass/fail criteria
• Test cases defined
• Validation plan is actionable

---

Next Steps

After completing skill planning:

1. Review Plan

   • Validate completeness
   • Get feedback if team skill
   • Adjust based on feedback

2. Proceed to Implementation

   • Use skill-builder-generic for implementation
   • Follow file structure from plan
   • Reference estimates for time management

3. Track Progress

   • Use task-development to break down implementation
   • Use todo-management to track progress
   • Adjust plan if significant deviations

4. Validate Continuously

   • Run validations frequently
   • Test as you build
   • Iterate based on findings

---

Quick Reference

The 6-Step Planning Process

| Step | Focus | Key Output | Time | |------|-------|------------|------| | 1. Analyze Requirements | Problem, users, scope, domain | Requirements document | 30-60m | | 2. Choose Pattern | Workflow/task/reference/capabilities | Pattern selection with rationale | 15-30m | | 3. Design Structure | Files, sections, progressive disclosure | File structure plan | 30-45m | | 4. Plan Content | Section-by-section content outline | Content plan | 45-90m | | 5. Estimate Complexity | Time, dependencies, risks | Effort estimate | 20-30m | | 6. Create Plan Document | Consolidated implementation plan | Complete skill plan | 30-45m |

Total Planning Time: 3-5 hours for comprehensive plan

The 4 Organizational Patterns

| Pattern | When to Use | Structure | Example | |---------|-------------|-----------|---------| | Workflow | Sequential dependencies, process with steps | Numbered steps (Step 1→2→3) | deployment-guide, development-workflow | | Task | Independent operations, no required order | Unnumbered operations | railway-troubleshooting, review-multi | | Reference | Standards, guidelines, design systems | Topic-based sections | botanical-design, common-patterns | | Capabilities | Multiple related features used together | Integrated capabilities | Complex multi-feature skills |

Pattern Selection Decision Tree

Do steps have sequential dependencies?
├─ Yes → WORKFLOW (use numbered steps)
└─ No → Are operations independent?
    ├─ Yes → TASK (use unnumbered operations)
    └─ No → Is it standards/guidelines?
        ├─ Yes → REFERENCE (topic-based organization)
        └─ No → CAPABILITIES (integrated features)

Complexity Estimation Guidelines

| Complexity | Files | Lines | Time | Characteristics | |------------|-------|-------|------|-----------------| | Simple | 1-3 | 400-800 | 2-4h | Single file or minimal references | | Medium | 4-8 | 1,500-3,000 | 8-15h | Multiple references, maybe scripts | | Complex | 9-15+ | 3,000-5,000+ | 20-40h | Extensive references, automation scripts |

Progressive Disclosure Rules

• SKILL.md: <1,200 lines ideal (overview + essentials)
• references/: 300-600 lines per file (detailed guides)
• scripts/: Automation tools (loaded when needed)

Decision: If content >1,000 lines → move detailed content to references/

Common Planning Outputs

Requirements Document:

• Problem definition
• User analysis
• Scope boundaries
• Domain knowledge capture

Structure Plan:

• File organization
• Section outline
• Progressive disclosure strategy
• Naming conventions

Implementation Plan:

• Complete file-by-file breakdown
• Content specifications
• Time estimates
• Dependencies identified
• Validation criteria

Quick Planning Checklist

• [ ] Problem clearly defined (what, who, why)
• [ ] Users identified (expertise level, context)
• [ ] Scope boundaries established (in/out of scope)
• [ ] Pattern selected with rationale
• [ ] File structure designed
• [ ] Content planned section-by-section
• [ ] Complexity estimated (simple/medium/complex)
• [ ] Dependencies identified
• [ ] Time budget allocated
• [ ] Plan document created

For More Information

• Requirements analysis: See Step 1
• Pattern selection: See Step 2 + references/pattern-selection-guide.md
• Structure design: See Step 3 + references/structure-planning-guide.md
• Content planning: See Step 4 + references/content-specification-guide.md
• Complexity estimation: See Step 5 + references/complexity-assessment-guide.md

---

planning-architect is the foundation of systematic skill development. Use it to transform ideas into actionable implementation plans that lead to high-quality, well-structured Claude Code skills.