planning-architect
GitHub用于系统规划Claude Code技能开发，从概念到实施蓝图。涵盖需求分析、结构选择、复杂度估算及依赖识别，旨在生成可执行的详细计划，防止返工并提升设计质量。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill planning-architect -g -y
SKILL.md
Frontmatter
{
"name": "planning-architect",
"description": "Comprehensive skill development planning. Analyzes requirements, chooses organizational patterns (workflow\/task\/reference\/capabilities), defines structure, estimates complexity, identifies dependencies, and creates detailed implementation plan. Use when planning new skills, converting documentation to skills, or architecting complex skill systems.",
"allowed-tools": "Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch"
}
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(notguide1.md)complexity-estimation-techniques.md(notcomplexity.md)advanced-workflows.md(notadvanced.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:
- 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:
-
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
- 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.
Version History
- e0220ca Current 2026-07-05 23:12
