@rfxlamia/skillkit 1.0.0 → 1.2.0

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)**

package/skills/skillkit-help/knowledge/foundation/06-platform-constraints.md

@@ -0,0 +1,237 @@
+---
+title: "Platform Constraints & Technical Limitations"
+purpose: "Understanding technical limitations and workarounds"
+token_estimate: "2000"
+read_priority: "medium"
+read_when:
+  - "User asking 'Can Skills do X?'"
+  - "Troubleshooting deployment issues"
+  - "Enterprise planning"
+  - "Team coordination questions"
+  - "Platform compatibility questions"
+related_files:
+  must_read_first:
+    - "01-why-skills-exist.md"
+  read_together:
+    - "07-security-concerns.md"
+  read_next:
+    - "08-when-not-to-use-skills.md"
+avoid_reading_when:
+  - "User just learning concepts"
+  - "Not yet implementing"
+  - "Personal use only (not team)"
+last_updated: "2025-11-01"
+---
+
+# Platform Constraints & Technical Limitations
+
+## I. INTRODUCTION
+
+Skills provide powerful extensibility but come with platform-specific constraints and technical limitations that must be understood for successful deployment, especially in enterprise contexts.
+
+**Critical Dependencies:** Filesystem access (absolute requirement), Code execution environment (cannot function without), Platform-specific deployment methods (varies by Claude.ai/API/Code).
+
+**Why This Matters:** Understanding limitations prevents unrealistic expectations, enables informed architecture decisions, and helps plan workarounds for deployment challenges.
+
+**This file addresses practical constraints. For security risks, see:** `07-security-concerns.md`
+
+---
+
+## II. DEPLOYMENT LIMITATIONS
+
+### A. User Skills Only (No Organization-Wide Deployment)
+
+**Current State (as of October 2025):** Custom skills are private to individual user accounts. No organization-wide deployment mechanism exists yet.
+
+**Platform-Specific Methods:**
+
+| Platform | Upload Method | Limit | Sharing |
+|----------|---------------|-------|---------|
+| Claude.ai/Desktop | Settings → Capabilities → Skills → Upload ZIP | 20 per user | Manual each user |
+| Claude Code | Copy to `~/.claude/skills/` (personal) or `.claude/skills/` (project) | Unlimited | Git repository |
+| API | `client.skills.create()` programmatic upload | Unlimited | Skill ID references |
+
+**Enterprise Impact:** Teams of 10+ people require significant manual coordination. Version drift common without strict processes. Each team member must upload skills separately.
+
+### B. Manual Distribution (No Centralized Marketplace)
+
+**Distribution Methods Table:**
+
+| Method | Best For | Pros | Cons |
+|--------|----------|------|------|
+| Git Repository | Team collaboration | Version control, auditability | Manual install still required |
+| ZIP Files | Simple sharing | Easy distribution | No version tracking, no dependencies |
+| Internal Portal | Large organizations | Centralized access | Still requires manual user action |
+
+**Official Anthropic Skills:** Only 4 pre-built skills available (PowerPoint, Excel, Word, PDF), automatically enabled. Community skills: None officially curated yet.
+
+**Marketplace Status:** No official Skills marketplace exists (as of October 2025). Enterprise-wide deployment capabilities listed as "coming soon" but not ready. Timeline unknown.
+
+### C. Enterprise Deployment Challenges
+
+**Key Problems:**
+
+**Version Control:** No automated update mechanism. Teams must coordinate versions manually. Testing updates across team required. Rollback: Manual only.
+
+**Governance:** No approval workflows, no audit trails for skill usage, no centralized management console. Compliance tracking: Custom solutions needed.
+
+**Support:** No official debugging tools, limited error reporting. Troubleshooting requires technical expertise.
+
+**For context on official skills, see:** `01-why-skills-exist.md`
+
+---
+
+## III. TECHNICAL CONSTRAINTS
+
+### A. Absolute Filesystem Dependency
+
+**Core Requirement:** Skills REQUIRE filesystem access and code execution capabilities. Won't work without these features enabled.
+
+**Platform Availability:**
+
+| Platform | Filesystem | Code Execution | Skills Support |
+|----------|------------|----------------|----------------|
+| Claude.ai (Paid) | Yes | Yes | Full |
+| Claude Desktop | Yes | Yes | Full |
+| Claude Code CLI | Yes | Yes | Full |
+| API (with betas) | Sandboxed | Sandboxed | Full |
+| Claude.ai (Free) | No | No | NONE |
+| Mobile Apps | Limited | No | NONE |
+
+**Critical Distinction:** Biggest difference from previous approaches like MCP or ChatGPT Plugins which don't require code execution infrastructure.
+
+### B. Platform-Specific Differences
+
+**Comprehensive Comparison: Claude.ai vs API vs Code**
+
+| Feature | Claude.ai/Desktop | Claude Code CLI | Anthropic API |
+|---------|-------------------|-----------------|---------------|
+| **Format** | ZIP file | Folder structure | ZIP file |
+| **Skill Limit** | 20 per user | Unlimited | Unlimited |
+| **Distribution** | Manual upload | Git/filesystem | Programmatic |
+| **Network (Scripts)** | Yes (npm/PyPI install) | Yes | NO (sandboxed) |
+| **External APIs** | Accessible | Accessible | NOT accessible |
+| **Runtime Packages** | Install dynamically | Install dynamically | Pre-installed only |
+| **Sharing** | Manual per user | Git repository | Skill ID refs |
+
+**Critical API Limitation:** NO network access from code execution container. Cannot install packages at runtime. Only pre-installed packages available. Cannot access external APIs directly.
+
+**Impact:** API deployments require pre-packaging ALL dependencies. Cannot dynamically fetch data during execution.
+
+**For tool security boundaries with Subagents, see:** `02-skills-vs-subagents-comparison.md`
+
+### C. Sandboxed Execution Environment
+
+**Security Container:** All Skills run in sandboxed environment with restricted permissions.
+
+**Default Restrictions:** No access to user's local filesystem (outside container), no system resources, no privileged operations, no persistent storage between conversations.
+
+**Tool Permissions:** Use `allowed-tools` in YAML to restrict:
+
+```yaml
+allowed-tools: "Read,Write,Bash(git:*)"
+# Allows: Read, Write, git commands only
+# Blocks: other Bash commands
+```
+
+**Resource Limits:** Memory limited (exact limits undocumented), CPU shared, execution timeouts exist (not publicly specified), large files may cause issues.
+
+---
+
+## IV. EXECUTION LIMITATIONS
+
+### A. Discovery and Triggering Issues
+
+**LLM-Based Routing:** Skills use pure LLM-based discovery (no algorithmic selection). Claude evaluates skill descriptions against conversation context.
+
+**Common Problems:**
+
+**Vague Descriptions Prevent Activation:**
+```yaml
+# BAD (won't trigger reliably)
+description: "Helps with documents"
+
+# GOOD (clear triggers)
+description: "Convert PDF files to Excel spreadsheets. Use when user mentions PDF conversion or Excel export"
+```
+
+**Phrasing Mismatch:** User says "Transform PDF to spreadsheet" but skill description says "Convert documents to XLSX" → May not trigger.
+
+**Solution:** Use multiple synonyms in description: "Convert, transform, export, change PDF files to Excel, XLSX, spreadsheet format"
+
+**Balancing Act:** Descriptions must be specific enough to prevent false positives, broad enough to catch valid use cases.
+
+### B. Script Best Practices
+
+**Execution Model:** Scripts execute via bash. Output only (not code contents) consumes tokens.
+
+**Key Practices:**
+
+**1. Error Handling:**
+```python
+try:
+    result = process_data(input_file)
+    print(json.dumps({"status": "success", "result": result}))
+except Exception as e:
+    print(json.dumps({"status": "error", "message": str(e)}))
+```
+
+**2. Structured Output:**
+```python
+# GOOD: JSON (easy parsing)
+print(json.dumps({"findings": [...], "summary": "..."}))
+
+# BAD: Unstructured text
+print("Found some issues... maybe check line 45...")
+```
+
+**API Constraint:** Remember sandboxed environment - no external network calls from scripts.
+
+### C. Resource and Performance Considerations
+
+**Observed Limits:** Single script execution ~5-10 minutes timeout. Memory sufficient for typical tasks, issues with large datasets (>1GB). Large files (>100MB) may be slow.
+
+**Optimization:** Use progressive disclosure effectively. Keep SKILL.md lean, move heavy content to references.
+
+**For token optimization strategies, see:** `05-token-economics.md`
+
+---
+
+## V. WORKAROUNDS SUMMARY
+
+**Key Solutions for Major Limitations:**
+
+| Problem | Workaround |
+|---------|------------|
+| No org-wide deployment | Git repository + installation docs. Create setup scripts. |
+| No marketplace | Internal skills library (Git). Curated collection with README. |
+| Version synchronization | Semantic versioning in metadata. Team communication channel. Testing protocols. |
+| API no network | Pre-package all data. Use main conversation to fetch external data (Claude web tools), pass to skill. |
+| Discovery unreliable | Engineer descriptions with multiple synonyms. Test various phrasings. Include explicit triggers. |
+| Platform differences | Document platform-specific behavior. Test on target platform. Provide platform instructions. |
+| No governance | Internal approval process. Code review for all skills. Security audit checklist. |
+| Resource limits | Split operations into chunks. Process incrementally. Use streaming where possible. |
+
+**For enterprise adoption strategies, see:** `adoption-strategy.md` (when available)
+
+---
+
+## WHEN TO READ NEXT
+
+**For Security Concerns:**
+- Security risks and mitigations → `07-security-concerns.md`
+
+**For Decision Making:**
+- When NOT to use Skills → `08-when-not-to-use-skills.md`
+- Should I use Skills or Subagents? → `03-skills-vs-subagents-decision-tree.md`
+
+**For Implementation:**
+- Token optimization → `05-token-economics.md`
+- Hybrid patterns → `04-hybrid-patterns.md`
+
+**For Strategic Context:**
+- Why Skills exist → `01-why-skills-exist.md`
+
+---
+
+**FILE END - Estimated Token Count: ~2,000 tokens (~236 lines)**