@rfxlamia/skillkit 1.1.0 → 1.2.0

package/skills/skillkit-help/knowledge/foundation/02-skills-vs-subagents-comparison.md

@@ -0,0 +1,312 @@
+---
+title: "Skills vs Subagents: Conceptual Differences"
+purpose: "Fundamental understanding of Skills vs Subagents differences"
+token_estimate: "2400"
+read_priority: "critical"
+read_when:
+  - "User confused about Skills vs Subagents"
+  - "User asking 'What's the difference?'"
+  - "Before reading decision tree"
+  - "Comparing approaches"
+  - "Understanding architecture"
+related_files:
+  must_read_first:
+    - "01-why-skills-exist.md"
+  read_together:
+    - "03-skills-vs-subagents-decision-tree.md"
+  read_next:
+    - "04-hybrid-patterns.md"
+    - "05-token-economics.md"
+avoid_reading_when:
+  - "User already understands distinction clearly"
+  - "User only needs decision guidance (skip to 03-decision-tree)"
+  - "User asking about costs only (skip to 05-token-economics)"
+last_updated: "2025-10-31"
+---
+
+# Skills vs Subagents: Conceptual Differences
+
+## I. INTRODUCTION
+
+Skills and Subagents are two fundamentally different extensibility mechanisms, serving distinct purposes. Understanding when to use each is critical for building effective AI workflows.
+
+**Core Distinction:**
+- **Skills** = Modular capability packages (instructions + resources)
+- **Subagents** = Pre-configured AI personalities (specialized workers)
+
+**Key Insight:** This is not an either/or choice. Most powerful workflows use BOTH - Skills for utilities, Subagents for orchestration.
+
+**This file addresses conceptual differences. For decision guidance, see:** `03-skills-vs-subagents-decision-tree.md`
+
+---
+
+## II. SKILLS: "HOW-TO" INSTRUCTIONS
+
+### Definition and Structure
+
+**Claude Skills** are modular, reusable capability packages containing instructions, scripts, and resources.
+
+**Structure:** Folder with SKILL.md file (YAML frontmatter + markdown body), plus optional scripts, references, assets.
+
+**Primary Function:** Extend Claude's knowledge with procedural "how-to" information.
+
+### Mental Model: Recipe Cards
+
+Think of Skills like recipe cards in a cookbook:
+- Each card contains specific instructions
+- Pull out card when needed
+- Multiple cards can be used together
+- Instructions stay same, execution adapts to context
+
+### 6 Key Characteristics
+
+**1. Automatic Discovery**
+Claude evaluates all skill descriptions against conversation context and loads relevant skills automatically. NO explicit user command needed.
+
+**2. Shared Context Window**
+Skills pull necessary information to current chat. Act as quick add-ons for single tasks. NO separate context window.
+
+**3. Progressive Disclosure**
+- Level 1: Metadata always loaded (30-50 tokens)
+- Level 2: SKILL.md loaded when triggered
+- Level 3: References loaded on-demand
+- Extreme token efficiency
+
+**4. Procedural Knowledge Focus**
+"How-to" instructions, domain-specific procedures, organizational standards, templates and formats.
+
+**5. Composability**
+Multiple skills can be loaded simultaneously and stack together seamlessly. Reusable across different contexts.
+
+**6. Tool Access Inheritance**
+Uses main Claude's tools. All tools available that are given to main conversation.
+
+### Best Use Cases
+
+**Single, Well-Defined Tasks:**
+- File conversions (PDF to Excel)
+- Template applications (brand guidelines)
+- Domain knowledge reference (API docs)
+- Utility functions (validation, transformation)
+
+**Examples:** Brand guidelines enforcement, code style guides, financial modeling procedures, document processing.
+
+**For detailed patterns, see:** `references/workflows.md`
+
+---
+
+## III. SUBAGENTS: AI WORKER
+
+### Definition and Structure
+
+**Claude Subagents** are pre-configured AI personalities with specialized system prompts.
+
+**Structure:** Markdown file with YAML frontmatter defining role, tools, system prompt, optional skill invocations.
+
+**Primary Function:** Handle complex, multi-step workflows requiring dedicated focus.
+
+### Mental Model: Specialist Team Members
+
+Think of Subagents like specialist team members:
+- Each expert has specialized role
+- Works independently with own workspace
+- Can be called explicitly or delegate automatically
+- Returns results when done
+
+### 6 Key Characteristics
+
+**1. Dual Invocation Pattern**
+Automatic delegation (Claude spawns specialized agents) OR explicit invocation ("@agent-name" or "Use the X subagent"). User has direct control.
+
+**2. Isolated Context Window**
+Operates in separate, dedicated context window. Complete isolation prevents "context pollution". Can focus entirely on specific task.
+
+**3. Specialized Personality**
+Pre-configured role and expertise. Domain-specific system prompts. Consistent behavior patterns.
+
+**4. Multi-Step Workflow Capability**
+Handles complex sequences with decision points, multiple queries and synthesis, iterative hypothesis testing.
+
+**5. Restricted Tool Permissions**
+Can have specific tool permissions. Example: code-reviewer gets Read/Grep/Glob only, NO Write/Edit. Security boundaries maintained.
+
+**6. Higher Token Consumption**
+Dedicated context per agent. Multi-agent systems use approximately 15x more tokens. Justified for high-value complex tasks.
+
+### Best Use Cases
+
+**Complex, Multi-Step Workflows:**
+- Code review processes with multiple stages
+- Data analysis requiring multiple queries and synthesis
+- Debugging with iterative hypothesis testing
+- Security audits with comprehensive checks
+
+**Examples:** ticket-researcher (downloads attachments, analyzes, compares), code reviewer (multiple validation passes), security auditor (comprehensive scanning).
+
+**For orchestration patterns, see:** `04-hybrid-patterns.md`
+
+---
+
+## IV. COMPARISON MATRIX
+
+### Core Differences Table
+
+| Dimension | Skills | Subagents |
+|-----------|--------|-----------|
+| **Mental Model** | Recipe cards, plugins | Team members, consultants |
+| **Context Window** | Shared main context | Separate isolated context |
+| **Invocation** | Automatic only | Automatic AND explicit |
+| **Token Overhead** | 30-50 tokens until used | 15x full conversations |
+| **Best For** | Single tasks, utilities | Multi-step workflows |
+| **Tool Access** | Inherits all main tools | Can be restricted |
+| **Composability** | Stack multiple skills | Coordinate multiple agents |
+| **Control** | Automatic discovery | Explicit or automatic |
+
+### Invocation Pattern Examples
+
+**Skills Invocation:**
+```
+User: "Convert this PDF to Excel"
+[Claude evaluates skill descriptions]
+[pdf-processing skill automatically loaded]
+[Task completed in main conversation]
+```
+
+**Subagents Invocation:**
+```
+User: "Review this codebase for security issues"
+[Claude recognizes complex multi-step task]
+[Spawns security-reviewer subagent]
+[Subagent works in isolated context]
+[Returns comprehensive report]
+```
+
+### Token Efficiency Comparison
+
+**Skills Example:**
+- Metadata: 50 tokens
+- SKILL.md when triggered: 800 tokens
+- **Total: 850 tokens**
+
+**Subagent Example:**
+- Full system prompt: 2,000 tokens
+- Conversation history: 3,000 tokens
+- Analysis output: 2,000 tokens
+- **Total: 7,000 tokens (8.2x more)**
+
+Multi-agent systems use approximately 15x more tokens than single conversations. Justified for complex, high-value tasks.
+
+**For detailed token economics, see:** `05-token-economics.md`
+
+### Tool Access Comparison
+
+**Skills:** Uses all tools available to main Claude. NO independent tool restrictions. Inherits permissions automatically.
+
+**Subagents:** Can have specific tool permissions (e.g., code-reviewer restricted to Read/Grep/Glob only). Security boundaries maintained.
+
+**Security Implication:** Subagents provide tool isolation - skills do not. Choose subagent when tool restrictions needed.
+
+### Use Case Decision Reference
+
+| Use Case Type | Recommended | Reasoning |
+|---------------|-------------|-----------|
+| File conversion | Skill | Single task, utility |
+| Code review | Subagent | Multi-step analysis |
+| Brand guidelines | Skill | Standards reference |
+| Security audit | Subagent | Complex workflow |
+| Data transformation | Skill | Deterministic utility |
+| Exploratory analysis | Subagent | Iterative reasoning |
+| API documentation | Skill | Reference knowledge |
+| Debugging session | Subagent | Multi-step investigation |
+
+### Maintenance Differences
+
+**Skills:** Update SKILL.md instructions, add/modify scripts, version control straightforward, reusable across contexts, easier to maintain (smaller scope).
+
+**Subagents:** Update system prompts, modify role definitions, test behavior extensively, context-specific tuning, more complex (broader scope).
+
+**Real Example:** Subagent reduced from 803 lines to 281 lines (65% reduction) by extracting templates to separate skill file. Skills enable subagent efficiency.
+
+### Performance Validation
+
+**Skills:** Fast invocation, minimal overhead, scales well (50+ skills manageable), consistent behavior.
+
+**Subagents:** Anthropic research shows Claude Opus 4 + Sonnet 4 subagents outperforms single-agent Opus 4 by **90.2%** on complex research tasks. Higher token cost justified by capability.
+
+---
+
+## V. KEY TAKEAWAYS
+
+### Simple Rule of Thumb
+
+**Start with Skill unless you specifically need Subagent features.**
+
+Skills simpler, faster, and easier to maintain. Upgrade to Subagent when you're doing actual workflows with multiple steps, decision points, and validation loops.
+
+**For detailed decision framework with scoring system, see:** `03-skills-vs-subagents-decision-tree.md`
+
+### They Work Together (Not Either/Or)
+
+Skills and Subagents are designed to work together and highly complementary.
+
+**The Hybrid Pattern:**
+- Subagent handles complex workflow and orchestration
+- Skill handles utility functions
+- Clean separation of concerns
+- Reusable components
+
+**Example:** ticket-researcher subagent downloads ticket attachment, invokes document-reader skill to convert to text, continues analysis.
+
+**For hybrid implementation patterns, see:** `04-hybrid-patterns.md`
+
+### Cost vs Capability Trade-off
+
+**Skills:** Very cost-efficient (30-50 tokens overhead). Best for frequent, lightweight tasks. Scale well.
+
+**Subagents:** Higher cost (15x token multiplier). Justified for complex, high-value tasks. Best for infrequent, critical workflows.
+
+**Optimization Strategy:** Use Skills to reduce duplication across subagents. Extract common templates to skills. Subagents invoke skills for utilities.
+
+**Validated Result:** Subagent system prompt reduced 65% (803→281 lines) with zero functionality lost.
+
+### When to Choose Each
+
+**Choose Skills When:**
+- Repeatable workflows you've figured out
+- Tasks requiring organizational standards
+- Building blocks reusable across contexts
+- Token efficiency critical
+
+**Choose Subagents When:**
+- Complex multi-step workflows with decision points
+- Specialized domain expertise requiring dedicated focus
+- Tasks that would clutter main conversation
+- Isolated context required
+
+**Choose Both (Hybrid) When:**
+- Complex orchestration + reusable utilities
+- Multiple specialized agents sharing common functions
+- Cost optimization without sacrificing capability
+
+---
+
+## WHEN TO READ NEXT
+
+**For Decision Making:**
+- Need decision framework? → `03-skills-vs-subagents-decision-tree.md`
+- Want hybrid patterns? → `04-hybrid-patterns.md`
+
+**For Cost Analysis:**
+- Token economics details → `05-token-economics.md`
+
+**For Implementation:**
+- Technical architecture → `technical-architecture.md`
+- Platform constraints → `06-platform-constraints.md`
+- Security concerns → `07-security-concerns.md`
+
+**If Clear on Differences:**
+- Skip to decision tree → `03-skills-vs-subagents-decision-tree.md`
+
+---
+
+**FILE END - Estimated Token Count: ~2,400 tokens (~335 lines)**

package/skills/skillkit-help/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)**