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:

Problem Definition: Clear understanding of what problem the skill solves
Domain Knowledge: Familiarity with the domain being captured
User Context: Understanding of who will use the skill and how
Existing Resources: Any documentation, examples, or patterns to reference
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:

Define the Problem
- What specific problem does this skill solve?
- What pain point does it address?
- What would happen without this skill?
Identify Target Users
- Who will use this skill? (You, team, community)
- What is their expertise level?
- What context will they invoke it in?
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?
Determine Scope
- What is explicitly in scope?
- What is explicitly out of scope?
- What are the boundaries?
- What is the minimum viable skill?
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:

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
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
scripts/ (Loaded When Executed)
- Target: Any size
- Content: Automation helpers, validation tools, generators
- Purpose: Executable tools that extend skill capabilities
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:

By Topic (Most Common)

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

By Depth (Progressive Learning)

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

By Workflow Step (For Workflow-Based)

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

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:

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
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)
Domain Complexity
- Familiar domain: 1x multiplier
- Some learning needed: 1.5x multiplier
- Significant research needed: 2x multiplier
- Novel/complex domain: 2.5x+ multiplier
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
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:

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:

Requirements Document
- Problem statement
- User profile
- Domain knowledge scope
- Explicit scope boundaries
- Resource inventory
Pattern Selection
- Chosen pattern with justification
- Rejected patterns with reasons
File Structure Plan
- Complete directory tree
- File names for all files
- Content allocation (what goes where)
- Progressive disclosure strategy
Time Estimate
- Overall estimate with range
- Breakdown by component
- Complexity factors applied
- Buffer included
Dependency Map
- Skill dependencies (required + optional)
- Tool dependencies
- Knowledge prerequisites
- Reverse dependencies
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

Start with Why
- Clearly articulate the problem
- Validate the need before planning
- Consider if skill is the right solution
Choose Pattern Carefully
- Pattern drives entire structure
- Consider user mental model
- Validate pattern with examples
Plan for Evolution
- Skills will grow over time
- Structure should accommodate additions
- Leave room for future enhancements
Optimize Context Usage
- Keep SKILL.md lean
- Move details to references
- Every word costs context tokens
Validate Early
- Review plan before implementation
- Get feedback from potential users
- Adjust based on feedback

Common Planning Mistakes

Scope Creep
- Problem: Planning too much at once
- Solution: Define MVP, plan iterations
Wrong Pattern
- Problem: Choosing workflow for independent tasks
- Solution: Use decision tree carefully
Poor Progressive Disclosure
- Problem: Putting everything in SKILL.md
- Solution: Follow <5,000 word guideline
Underestimating Complexity
- Problem: Unrealistic time estimates
- Solution: Use formula, add buffer
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:

Review Plan
- Validate completeness
- Get feedback if team skill
- Adjust based on feedback
Proceed to Implementation
- Use skill-builder-generic for implementation
- Follow file structure from plan
- Reference estimates for time management
Track Progress
- Use task-development to break down implementation
- Use todo-management to track progress
- Adjust plan if significant deviations
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

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.