@rfxlamia/skillkit 1.0.0

package/skills/skillkit/knowledge/foundation/03-skills-vs-subagents-decision-tree.md

@@ -0,0 +1,346 @@
+---
+title: "Decision Tree: Choosing Skills or Subagents"
+purpose: "Practical framework for Skills vs Subagents decision-making"
+token_estimate: "2400"
+read_priority: "critical"
+read_when:
+  - "User asking 'Should I use Skill or Subagent for X?'"
+  - "User needs decision guidance"
+  - "User describing a use case"
+  - "User wants recommendation"
+  - "Before starting implementation"
+related_files:
+  must_read_first:
+    - "02-skills-vs-subagents-comparison.md"
+  read_together:
+    - "04-hybrid-patterns.md"
+  read_next:
+    - "05-token-economics.md"
+avoid_reading_when:
+  - "User already decided (skip to implementation)"
+  - "User only needs conceptual understanding (read 02 only)"
+  - "User asking about costs (skip to 05)"
+last_updated: "2025-10-31"
+---
+
+# Decision Tree: Choosing Skills or Subagents
+
+## I. INTRODUCTION
+
+This file provides practical decision framework for choosing between Skills and Subagents using 8-question scoring system.
+
+**Prerequisites:** Understand conceptual differences first (see `02-skills-vs-subagents-comparison.md`)
+
+**How This Works:** Answer 8 questions about your use case. Each answer scores +1 (favors Skill), -1 (favors Subagent), or 0 (neutral). Calculate confidence score for recommendation with reasoning.
+
+**Important:** This is guidance framework, not rigid rules. Consider context and specific requirements.
+
+---
+
+## II. DECISION FLOWCHART
+
+Quick visual guide for decision process:
+
+```
+Is it a utility/conversion/template?
+├─ YES → SKILL (+1)
+└─ NO → Continue
+
+Does it need multiple steps of reasoning?
+├─ YES → SUBAGENT (-1)
+└─ NO → Continue
+
+Will it be reused as building block?
+├─ YES → SKILL (+1)
+└─ NO → Continue
+
+Does it need specialized personality?
+├─ YES → SUBAGENT (-1)
+└─ NO → Continue
+
+Is it knowledge Claude doesn't have?
+├─ YES → SKILL (+1)
+└─ NO → Continue
+
+Does it coordinate operations?
+├─ YES → SUBAGENT (-1)
+└─ NO → Continue
+
+Does it need isolated context?
+├─ YES → SUBAGENT (-1)
+└─ NO → Continue
+
+Would it clutter main chat?
+├─ YES → SUBAGENT (-1)
+└─ NO → SKILL (+1)
+
+SCORE INTERPRETATION:
++6 to +8: Strong Skill
++3 to +5: Moderate Skill
+-1 to +2: Consider Hybrid
+-3 to -5: Moderate Subagent
+-6 to -8: Strong Subagent
+```
+
+---
+
+## III. 8 KEY QUESTIONS
+
+### Q1: Is It a Utility/Conversion/Template Task?
+
+**Question:** Does the task primarily involve applying standard procedures, converting formats, or using templates?
+
+**Examples:**
+- YES: PDF to Excel conversion, brand guidelines application
+- NO: Code review with multiple validation stages
+
+**Scoring:** YES → +1 | NO → -1 | MAYBE → 0
+
+**Why:** Skills excel for well-defined procedural tasks (file conversions, template applications, utility functions).
+
+---
+
+### Q2: Does It Need Multiple Steps of Reasoning?
+
+**Question:** Does the task require multiple decision points, hypothesis testing, or iterative refinement?
+
+**Examples:**
+- YES: Code review (scan → analyze → prioritize → recommend)
+- NO: Apply coding style guide, extract text from PDF
+
+**Scoring:** YES → -1 | NO → +1 | MAYBE → 0
+
+**Why:** Subagents designed for complex workflows with multiple stages and synthesis requirements.
+
+---
+
+### Q3: Will It Be Reused as Building Block?
+
+**Question:** Will this capability be invoked by other workflows or agents as a utility?
+
+**Examples:**
+- YES: Document converter used by multiple subagents
+- NO: One-time analysis for specific project
+
+**Scoring:** YES → +1 | NO → -1 | MAYBE → 0
+
+**Why:** Skills are composable building blocks. Research validates 65% subagent reduction by extracting templates to skills.
+
+**For reusability patterns, see:** `04-hybrid-patterns.md`
+
+---
+
+### Q4: Does It Need Specialized Personality?
+
+**Question:** Does the task benefit from specialized role, tone, or domain-specific persona?
+
+**Examples:**
+- YES: Security auditor (paranoid perspective), code reviewer (strict standards)
+- NO: Format converter, template applier
+
+**Scoring:** YES → -1 | NO → +1 | MAYBE → 0
+
+**Why:** Subagents can embody specialized expertise with pre-configured AI personalities.
+
+---
+
+### Q5: Is It Knowledge Claude Doesn't Have?
+
+**Question:** Does the task require organizational procedures, proprietary methods, or domain-specific knowledge beyond Claude's training?
+
+**Examples:**
+- YES: Company WACC methodology, organizational workflows
+- NO: General code review principles, standard data analysis
+
+**Scoring:** YES → +1 | NO → 0 | MAYBE → +1
+
+**Why:** Skills extend Claude's knowledge with organizational procedures. Rakuten validates: "Skills streamline our workflows using our procedures."
+
+---
+
+### Q6: Does It Coordinate Operations with Decision Points?
+
+**Question:** Does the task involve orchestrating multiple operations with conditional logic and branching paths?
+
+**Examples:**
+- YES: Multi-stage validation (if fail → retry, if pass → continue)
+- NO: Linear transformation pipeline
+
+**Scoring:** YES → -1 | NO → +1 | MAYBE → 0
+
+**Why:** Subagents excel for coordination requiring multiple queries and synthesis.
+
+---
+
+### Q7: Does It Need Isolated Context?
+
+**Question:** Would the task benefit from separate context window to avoid pollution or confusion?
+
+**Examples:**
+- YES: Long debugging session, extensive exploration
+- NO: Quick utility function, template application
+
+**Scoring:** YES → -1 | NO → +1 | MAYBE → 0
+
+**Why:** Context isolation is a key Subagent feature preventing "context pollution" in main conversation.
+
+**For token efficiency analysis, see:** `05-token-economics.md`
+
+---
+
+### Q8: Would It Clutter Main Chat with Intermediate Steps?
+
+**Question:** Does the task generate substantial intermediate output that would overwhelm main conversation?
+
+**Examples:**
+- YES: Security scan with 50+ findings, comprehensive code analysis
+- NO: Single file conversion, template application
+
+**Scoring:** YES → -1 | NO → +1 | MAYBE → 0
+
+**Why:** Subagents return clean summaries, keeping main conversation focused.
+
+---
+
+## IV. CONFIDENCE SCORING
+
+### Calculation Method
+
+Sum your scores from 8 questions. Range: -8 (strong Subagent) to +8 (strong Skill).
+
+### Score Interpretation Table
+
+| Score Range | Recommendation | Characteristics | Token Cost | Complexity |
+|-------------|----------------|-----------------|------------|------------|
+| **+6 to +8** | STRONG SKILL | Utility functions, procedures | 30-50 tokens overhead | Low |
+| **+3 to +5** | MODERATE SKILL | Mostly procedural with some logic | Low overhead | Low-Medium |
+| **-1 to +2** | CONSIDER HYBRID | Mix of utility + orchestration | Optimized | Medium |
+| **-3 to -5** | MODERATE SUBAGENT | Multi-step with some structure | 15x multiplier | Medium-High |
+| **-6 to -8** | STRONG SUBAGENT | Complex workflows, expertise needed | High (justified) | High |
+
+### Confidence Modifiers
+
+**Increase Confidence in Skill IF:**
+- Task repeats frequently (token efficiency matters)
+- Multiple teams will use it (reusability critical)
+- Procedural knowledge well-documented
+- No iteration or exploration needed
+
+**Increase Confidence in Subagent IF:**
+- Task high-value and infrequent (cost justified)
+- Requires domain expertise personality
+- Involves exploration and discovery
+- Benefits from isolated context
+
+**Consider Hybrid IF:**
+- Score near neutral (-1 to +2)
+- Task has both utility and orchestration components
+- Want to optimize token efficiency while maintaining capability
+
+---
+
+## V. REAL-WORLD SCENARIOS
+
+### Scenario 1: Brand Guidelines Enforcement
+
+**Description:** Apply company logo, colors, fonts, tone to documents.
+
+**Scoring Analysis:**
+Q1-Q8: +1, +1, +1, +1, +1, +1, +1, +1 = **+8**
+
+**Recommendation:** STRONG SKILL
+
+**Reasoning:** Pure utility function with organizational knowledge. Research validates: "Skills apply brand style guidelines automatically."
+
+---
+
+### Scenario 2: Comprehensive Security Audit
+
+**Description:** Scan codebase for vulnerabilities, analyze severity, prioritize fixes, generate report.
+
+**Scoring Analysis:**
+Q1-Q8: -1, -1, 0, -1, 0, -1, -1, -1 = **-6**
+
+**Recommendation:** STRONG SUBAGENT
+
+**Reasoning:** Multi-step workflow with specialized expertise. Research validates: "Subagents excel for security audits with comprehensive checks."
+
+---
+
+### Scenario 3: Code Review Process
+
+**Description:** Review code for bugs, style violations, security issues, performance problems.
+
+**Scoring Analysis:**
+Q1-Q8: 0, -1, 0, -1, +1, -1, -1, -1 = **-4**
+
+**Recommendation:** MODERATE SUBAGENT + Skills (HYBRID)
+
+**Reasoning:** Complex workflow but uses company standards. HYBRID PATTERN: Subagent handles review process, invokes coding-standards Skill for rules.
+
+**For implementation, see:** `04-hybrid-patterns.md`
+
+---
+
+## VI. QUICK REFERENCE
+
+### Decision Cheat Sheet
+
+**Use SKILL if:**
+- Utility/conversion/template task
+- Single or linear workflow
+- Will be reused as building block
+- Organizational knowledge needed
+- Doesn't need personality
+- Won't clutter conversation
+
+**Use SUBAGENT if:**
+- Multi-step reasoning required
+- Needs specialized personality
+- Coordinates multiple operations
+- Benefits from isolated context
+- Would generate substantial output
+
+**Use HYBRID if:**
+- Has orchestration components (Subagent)
+- Uses reusable utilities (Skills)
+
+### Simple Rules
+
+**Start with Skill unless:**
+- You need multiple reasoning steps
+- You need specialized expertise personality
+- You need isolated context window
+- Intermediate steps would clutter main chat
+
+Skills are simpler, faster, easier to maintain. Upgrade to Subagent when complexity demands it.
+
+### Token Cost Quick Reference
+
+**Skills:** 30-50 tokens overhead (very efficient)  
+**Subagents:** 15x token multiplier (justified for complexity)  
+**Hybrid:** Optimizes both (Subagent orchestrates, Skills reduce duplication)
+
+**For detailed cost analysis, see:** `05-token-economics.md`
+
+---
+
+## WHEN TO READ NEXT
+
+**For Implementation:**
+- Decided Hybrid? → `04-hybrid-patterns.md`
+- Need cost details? → `05-token-economics.md`
+- Ready to build? → Implementation guides
+
+**For Context:**
+- Need conceptual review? → `02-skills-vs-subagents-comparison.md`
+- Want strategic context? → `01-why-skills-exist.md`
+- See detailed validation? → `case-studies.md`
+
+**For Constraints:**
+- Platform limitations? → `06-platform-constraints.md`
+- Security concerns? → `07-security-concerns.md`
+
+---
+
+**FILE END - Estimated Token Count: ~2,400 tokens (~326 lines)**

package/skills/skillkit/knowledge/foundation/04-hybrid-patterns.md

@@ -0,0 +1,308 @@
+---
+title: "Hybrid Patterns: Combining Skills + Subagents"
+purpose: "Best practices for using Skills and Subagents together"
+token_estimate: "2000"
+read_priority: "high"
+read_when:
+  - "User wants to combine Skills + Subagents"
+  - "Decision tree suggests hybrid"
+  - "User has complex workflow"
+  - "Optimizing existing multi-agent setup"
+  - "After understanding basics of both"
+related_files:
+  must_read_first:
+    - "02-skills-vs-subagents-comparison.md"
+  read_together:
+    - "05-token-economics.md"
+  read_next:
+    - "case-studies.md"
+avoid_reading_when:
+  - "User using pure Skills approach"
+  - "User using pure Subagents approach"
+  - "User just starting (too advanced)"
+  - "Simple use case doesn't need hybrid"
+last_updated: "2025-10-31"
+---
+
+# Hybrid Patterns: Combining Skills + Subagents
+
+## I. INTRODUCTION
+
+Skills and Subagents are designed to work together. Highly complementary.
+
+**Core Principle:**
+- Subagents: Orchestration, complex reasoning
+- Skills: Utilities, knowledge, templates
+- Together: Optimize capability AND efficiency
+
+**Research Validation:**
+- 65% subagent complexity reduction (803→281 lines)
+- 90.2% performance improvement (Opus 4 + Sonnet 4 subagents)
+- Zero functionality lost
+
+**When Hybrid Appropriate:**
+Decision tree score -1 to +1 indicates hybrid. Task has both orchestration AND utility components.
+
+**Prerequisites:** Understand Skills vs Subagents differences first.
+
+**For conceptual foundation, see:** `02-skills-vs-subagents-comparison.md`
+
+---
+
+## II. PATTERN 1: SUBAGENT ORCHESTRATION + UTILITIES
+
+### Pattern Description
+
+**Core Concept:** Subagent orchestrates workflow, invokes Skills for utility functions.
+
+**Architecture:**
+```
+Main Conversation
+    |
+Spawns Subagent (orchestrates complex workflow)
+    |
+    +-- Invokes Skill 1 (utility function)
+    +-- Invokes Skill 2 (utility function)
+    +-- Invokes Skill 3 (utility function)
+    |
+Subagent synthesizes results
+    |
+Returns to Main Conversation
+```
+
+**Key Characteristics:**
+- Clear separation: orchestration vs utilities
+- Skills reusable across multiple subagents
+- Efficient token usage (Skills loaded on-demand)
+- Clean workflow coordination
+
+### Implementation Example: Document Processing Pipeline
+
+**Scenario:** Process multiple PDFs with validation.
+
+**Setup:**
+- Subagent: document-processor (orchestrates)
+- Skill 1: pdf-converter (extracts text)
+- Skill 2: data-validator (checks format)
+- Skill 3: reporting-template (generates output)
+
+**Workflow:**
+```
+User: "Process these 10 PDFs and validate data"
+
+document-processor subagent:
+  FOR EACH pdf IN documents:
+    text = invoke pdf-converter skill
+    validation = invoke data-validator skill
+    IF valid:
+      aggregated_results.add(text, validation)
+  
+  report = invoke reporting-template skill
+  RETURN summary to main
+```
+
+**Benefits:**
+- Subagent handles iteration logic
+- Skills provide deterministic operations
+- Skills reusable by other workflows
+- Token efficient (Skills shared, not duplicated)
+
+### Implementation Checklist
+
+- [ ] Define subagent orchestration role
+- [ ] Identify reusable utilities → create Skills
+- [ ] Subagent system prompt references Skills
+- [ ] Test workflow end-to-end
+- [ ] Verify Skills invoked correctly
+
+---
+
+## III. PATTERN 2: MULTI-SUBAGENT + SHARED SKILLS
+
+### Pattern Description
+
+**Core Concept:** Multiple subagents share common Skills library. Extract duplicated knowledge to Skills.
+
+**Architecture:**
+```
+Before:
+Subagent A (800 lines: logic + templates + knowledge)
+Subagent B (750 lines: logic + DUPLICATE templates)
+Subagent C (700 lines: logic + DUPLICATE knowledge)
+
+After:
+Subagent A (250 lines: logic only)
+Subagent B (230 lines: logic only)
+Subagent C (220 lines: logic only)
+    |
+All invoke shared Skills:
+    +-- templates-skill (300 lines)
+    +-- standards-skill (200 lines)
+    +-- utilities-skill (150 lines)
+```
+
+**Real Validation:** Subagent reduced 803→281 lines (65%) by extracting templates to Skills. Zero functionality lost.
+
+**Key Benefit:** Update template once, all subagents benefit. DRY principle.
+
+### Implementation Example: Multi-Domain Content Pipeline
+
+**Scenario:** Blog, social media, email writers share brand guidelines.
+
+**Before Optimization:**
+- blog-writer: 700 lines (logic + brand + templates)
+- social-writer: 650 lines (logic + brand DUPLICATE + templates)
+- email-writer: 680 lines (logic + brand DUPLICATE + templates)
+- Total: 2,030 lines with extensive duplication
+
+**After Optimization:**
+- blog-writer: 220 lines (logic + blog-specific templates)
+- social-writer: 190 lines (logic + social-specific templates)
+- email-writer: 200 lines (logic + email-specific templates)
+- brand-guidelines skill: 250 lines (shared)
+- content-utilities skill: 150 lines (shared)
+- Total: 610 + 400 = 1,010 lines
+- Reduction: 50% fewer lines, zero functionality lost
+
+**Token Savings:**
+- Brand guidelines loaded once (250 lines)
+- Shared across 3 subagents
+- Instead of 250 × 3 = 750 lines loaded separately
+- Savings: 500 lines per workflow = 67% reduction for shared content
+
+**For detailed token analysis, see:** `05-token-economics.md`
+
+### Implementation Checklist
+
+- [ ] Audit subagent prompts for duplicated content
+- [ ] Extract common templates → Skills
+- [ ] Extract shared knowledge → Skills
+- [ ] Update subagent prompts to reference Skills
+- [ ] Test all subagents with new Skills
+- [ ] Measure token reduction
+
+---
+
+## IV. PATTERN 3: CONDITIONAL INVOCATION
+
+### Pattern Description
+
+**Core Concept:** Runtime decision - invoke Skill OR spawn Subagent based on task complexity evaluation.
+
+**Decision Logic:**
+```
+Task Received
+    |
+Evaluate Complexity
+    |
+    +-- Simple/Straightforward?
+    |       |
+    |       +-- Invoke Skill (fast, efficient)
+    |       +-- Cost: 800-2,000 tokens
+    |
+    +-- Complex/Multi-Step?
+            |
+            +-- Spawn Subagent (capable, thorough)
+            +-- Cost: 7,000-15,000 tokens (justified)
+```
+
+**Key Characteristics:**
+- Dynamic evaluation at runtime
+- Cost optimization through intelligent routing
+- Maintains capability when complexity demands it
+- Transparent decision logic
+
+### Implementation Example: Data Analysis Router
+
+**User Query:** "Analyze this dataset"
+
+**Decision Logic Implementation:**
+```
+Evaluate Dataset:
+  rows = dataset.row_count
+  metrics = required_analysis
+  
+Decision:
+  IF rows < 1,000 AND metrics == "basic":
+    → Invoke data-analysis Skill
+    → Quick summary statistics
+    → Time: 5 minutes
+    → Cost: 850 tokens
+    
+  ELIF rows > 1,000 OR metrics == "complex":
+    → Spawn data-scientist Subagent
+    → Comprehensive analysis with ML
+    → Time: 20 minutes
+    → Cost: 7,000 tokens (justified)
+```
+
+**Execution Path 1 (Simple - Skill):**
+- Dataset: 500 rows, basic statistics requested
+- Action: data-analysis Skill invoked
+- Process: Mean, median, std dev, visualizations
+- Output: Summary statistics report
+- Cost: 850 tokens ($0.0026)
+
+**Execution Path 2 (Complex - Subagent):**
+- Dataset: 50,000 rows, ML predictions needed
+- Action: data-scientist Subagent spawned
+- Process: Feature analysis, correlation matrix, model training, predictions
+- Output: Comprehensive analysis with ML insights
+- Cost: 7,000 tokens ($0.021, justified for ML work)
+
+**Decision Factors:**
+- Data volume (rows, columns, size)
+- Analysis complexity (descriptive vs predictive)
+- Time constraints (urgent vs thorough)
+- Output requirements (summary vs comprehensive)
+
+**Benefits:**
+- Simple tasks handled efficiently (Skill)
+- Complex tasks get full capability (Subagent)
+- Cost optimized automatically
+- User gets appropriate level of analysis
+
+### Implementation Checklist
+
+- [ ] Define complexity thresholds clearly
+- [ ] Implement decision logic (IF/THEN rules)
+- [ ] Create Skill for simple cases
+- [ ] Configure Subagent for complex cases
+- [ ] Test both execution paths
+- [ ] Monitor routing decisions for optimization
+
+---
+
+## V. BEST PRACTICES
+
+**Start Simple:** Begin with Pattern 1 (orchestration + utilities), scale to Pattern 2/3 when needed.
+
+**Separation of Concerns:** Subagents orchestrate workflows, Skills provide utilities. Clear boundaries.
+
+**Token Efficiency:** Extract duplicates to Skills immediately. Research validates 40-65% reduction.
+
+**Maintainability:** Update Skills once, all subagents benefit. Version control Skills separately.
+
+**Cost Optimization:** Use Pattern 3 for intelligent routing. Simple tasks→Skills (cheap), Complex→Subagents (justified).
+
+**Progressive Disclosure:** Design Skills with references. Main instructions + on-demand details.
+
+---
+
+## WHEN TO READ NEXT
+
+**For Cost Details:**
+Token economics analysis → `05-token-economics.md`
+
+**For Implementation:**
+Real-world validation → `case-studies.md`
+Platform constraints → `06-platform-constraints.md`
+Security considerations → `07-security-concerns.md`
+
+**If Starting Fresh:**
+Review conceptual differences → `02-skills-vs-subagents-comparison.md`
+Use decision framework → `03-skills-vs-subagents-decision-tree.md`
+
+---
+
+**FILE END - Estimated Token Count: ~2,000 tokens (~270 lines)**