@rfxlamia/skillkit 1.1.0 → 1.2.0

package/skills/skills/skillkit/knowledge/foundation/05-token-economics.md

@@ -0,0 +1,275 @@
+---
+title: "Token Economics: Cost Analysis Skills vs Subagents"
+purpose: "Understanding cost implications and optimization strategies"
+token_estimate: "2500"
+read_priority: "high"
+read_when:
+  - "User asking about costs"
+  - "User asking 'How much will this cost?'"
+  - "Budget planning"
+  - "ROI calculation needed"
+  - "Optimizing existing implementation"
+  - "Comparing cost of approaches"
+related_files:
+  must_read_first:
+    - "02-skills-vs-subagents-comparison.md"
+  read_together:
+    - "04-hybrid-patterns.md"
+  read_next: []
+avoid_reading_when:
+  - "User not concerned with costs"
+  - "Cost not decision factor"
+  - "Just exploring concepts"
+last_updated: "2025-11-01"
+---
+
+# Token Economics: Cost Analysis Skills vs Subagents
+
+## I. INTRODUCTION
+
+Token efficiency is a foundational advantage of Skills vs traditional approaches. Understanding token economics is critical for budget planning, architecture decisions, and cost optimization strategies.
+
+**Key Insight:** Skills use progressive disclosure for extreme efficiency (30-50 tokens overhead). Subagents use dedicated context windows (15× token multiplier). Neither approach is inherently "expensive" - appropriateness depends on use case frequency and value.
+
+**Pricing Context (Claude Sonnet 4.5):**
+- Input: $3 per million tokens
+- Output: $15 per million tokens
+
+**For architectural differences, see:** `02-skills-vs-subagents-comparison.md`
+
+---
+
+## II. SKILLS TOKEN MODEL
+
+### A. Progressive Disclosure Architecture (3 Levels)
+
+**Level 1 - Metadata (Always Loaded):**
+- Content: YAML frontmatter (name + description)
+- Token Cost: ~50 tokens per skill
+- When: Startup, every conversation
+- Purpose: Enable automatic discovery
+
+**Level 2 - Instructions (Triggered Loading):**
+- Content: Full SKILL.md body
+- Token Cost: <5,000 tokens (typically 800-2,800)
+- When: Skill determined relevant
+- Mechanism: `bash: read skill-name/SKILL.md`
+
+**Level 3+ - Resources (On-Demand):**
+- Content: References, documentation, datasets
+- Token Cost: 0 until accessed
+- When: Explicitly needed
+- Critical: Scripts execute WITHOUT loading contents - only output costs tokens
+
+### B. Token Efficiency Breakdown
+
+**Idle State (Skills Installed, Not Used):**
+```
+50 skills installed
+Each: ~50 tokens metadata
+Total overhead: 2,500 tokens
+Cost: $0.0075 per conversation
+```
+
+**Active State (Skill Triggered):**
+```
+Metadata: 50 tokens
+SKILL.md body: 800 tokens
+Total: 850 tokens
+Cost: $0.00255 per use
+```
+
+**Heavy Usage (With References):**
+```
+Metadata: 50 tokens
+SKILL.md: 800 tokens
+Reference file: 1,200 tokens
+Total: 2,050 tokens
+Cost: $0.00615 per use
+```
+
+### C. Real-World Example: PDF Processing Skill
+
+**Startup Loading:**
+- Description: "Extract text from PDFs, fill forms, merge documents"
+- Tokens: 50
+- Impact: Every conversation
+
+**User Request:** "Extract text from this PDF"
+
+**Skill Activation:**
+- Read SKILL.md: 800 tokens
+- Determines form filling NOT needed → FORMS.md: 0 tokens (not accessed)
+- Execute extraction script output: ~200 tokens
+- Total: 1,050 tokens
+
+**Cost Calculation:**
+- Input tokens: 850 (metadata + SKILL.md)
+- Output tokens: 200 (extraction results)
+- Cost: (850 × $3/M) + (200 × $15/M) = $0.00255 + $0.003 = $0.00555
+
+### D. Scaling Characteristics
+
+**Installing Many Skills:**
+- 10 skills: ~500 tokens overhead
+- 50 skills: ~2,500 tokens overhead
+- 100 skills: ~5,000 tokens overhead
+- Cost negligible until triggered
+
+**Key Advantage:** Unlimited bundled content (references, documentation, examples) with ZERO token penalty until accessed. Can include comprehensive materials without context window impact.
+
+**For optimization strategies combining multiple skills, see:** `04-hybrid-patterns.md`
+
+---
+
+## III. SUBAGENTS TOKEN MODEL
+
+### A. Full Context Architecture
+
+**Dedicated Context Window:**
+Subagents operate with separate, isolated context window containing:
+- Complete system prompt (1,500-3,000 tokens)
+- Full conversation history with subagent
+- All intermediate steps and reasoning
+- Final output synthesis
+
+**No Progressive Disclosure:** Unlike Skills, subagents load entire context immediately. All instructions present throughout conversation.
+
+### B. Token Consumption Breakdown
+
+**Single Subagent Invocation:**
+```
+System prompt: 2,000 tokens
+User query: 100 tokens
+Subagent reasoning: 500 tokens (multiple turns)
+Intermediate steps: 1,500 tokens
+Final output: 300 tokens
+Conversation history: 2,000 tokens
+Total: ~6,400 tokens per invocation
+```
+
+**Cost Calculation:**
+- Input: 6,100 tokens × $3/M = $0.0183
+- Output: 300 tokens × $15/M = $0.0045
+- Total: ~$0.023 per invocation
+
+### C. Multi-Agent Multiplier Effect
+
+**Critical Finding:** Multi-agent systems use approximately **15× more tokens** than single conversations.
+
+**Why 15× Multiplier:**
+1. Each agent: Dedicated context window
+2. Orchestration overhead: Agent coordination
+3. Context sharing: Information passed between agents
+4. Synthesis: Combining outputs
+5. Iteration: Multi-turn agent interactions
+
+**Example: 3-Agent System**
+```
+Main conversation: 2,000 tokens
+Agent A context: 5,000 tokens
+Agent B context: 4,500 tokens
+Agent C context: 4,000 tokens
+Orchestration: 1,500 tokens
+Synthesis: 1,000 tokens
+Total: ~18,000 tokens (9× single conversation)
+```
+
+**When 15× Justified:**
+- Complex, high-value workflows
+- Infrequent operations (not every conversation)
+- Quality improvement outweighs cost
+- Validated: Anthropic research shows 90.2% performance improvement Opus 4 + Sonnet 4 subagents
+
+### D. Cost-Benefit Analysis
+
+**Subagent Strengths:**
+- Isolated context prevents pollution
+- Specialized expertise per agent
+- Parallel processing capability
+- Superior for multi-step reasoning
+
+**Cost Reality:**
+- 7-15× more expensive than Skills
+- Justified for complex workflows
+- NOT appropriate for frequent, simple tasks
+- Use Skills for utilities, Subagents for orchestration
+
+**Validated Example:** Subagent system prompt reduced 65% (803→281 lines) with zero functionality lost by extracting templates to Skills.
+
+**For decision framework, see:** `03-skills-vs-subagents-decision-tree.md`
+
+---
+
+## IV. COST COMPARISON SCENARIOS
+
+**Comparison Table: Skills vs Subagents vs Hybrid**
+
+| Scenario | Frequency | Skills Cost/Use | Subagents Cost/Use | Monthly Cost (Skills) | Monthly Cost (Subagents) | Winner | Key Reason |
+|----------|-----------|-----------------|--------------------|-----------------------|--------------------------|--------|------------|
+| **Brand Guidelines** (Apply standards to docs) | 100×/month | $0.00255 (850t) | $0.015 (5,000t) | $0.26 | $1.50 | Skills | 83% savings, frequent simple task |
+| **Security Audit** (Multi-stage analysis) | 5×/month | $0.012 (4,000t) | $0.024 (8,000t) | $0.06 | $0.12 | Subagent | Multi-step reasoning, quality justified |
+| **Data Pipeline** (Extract, transform, analyze) | 50×/month | N/A (cannot orchestrate) | $0.03 (10,000t) | N/A | $1.50 | **Hybrid: $1.10** | Subagent (6kt) + Skills (1.4kt) = 7.4kt optimal |
+| **Document Processing** (PDF to Excel at scale) | 1,000×/month | $0.00255 (850t) | $0.015 (5,000t) | $2.55 | $15.00 | Skills | 83% savings at scale |
+
+**Key Insights:**
+- Frequent simple tasks → Skills (80%+ cost savings)
+- Infrequent complex workflows → Subagents (capability justifies cost)
+- Moderate complexity → Hybrid (optimizes both capability AND efficiency)
+
+**For hybrid implementation patterns, see:** `04-hybrid-patterns.md`
+
+---
+
+## V. OPTIMIZATION STRATEGIES
+
+### Architecture Optimization
+
+**1. Tiered Model Architecture**
+Use Opus 4 for orchestration + Sonnet 4.5 subagents for execution. Research validated: 40-60% cost reduction while maintaining quality.
+
+**2. Hybrid Pattern**
+Subagents orchestrate workflows, Skills provide utilities. Best balance of capability and cost.
+
+### Skills Optimization
+
+**3. Extract Duplication to Skills**
+Move common templates/knowledge from subagent prompts to Skills. Real validation: Subagent reduced 65% (803→281 lines) with zero functionality lost.
+
+**4. Progressive Loading**
+Structure Skills with granular references. Load only necessary sections. Avoid loading unused documentation.
+
+### Routing Optimization
+
+**5. Frequency-Based Routing**
+Frequent tasks → Skills. Infrequent, complex tasks → Subagents. Use conditional invocation pattern for dynamic routing.
+
+**6. Batch Processing**
+Group similar tasks to amortize subagent context setup costs. Single subagent invocation handles multiple items.
+
+### Monitoring & Iteration
+
+**7. Track Actual Usage**
+Monitor real token consumption. Optimize based on measured costs, not assumptions. Premature optimization wastes time - iterate based on data.
+
+**For conditional invocation pattern, see:** `04-hybrid-patterns.md` (Pattern 3)
+
+---
+
+## WHEN TO READ NEXT
+
+**For Implementation:**
+- Hybrid patterns → `04-hybrid-patterns.md`
+- Platform limits → `06-platform-constraints.md`
+
+**For Decision Making:**
+- Should I use Skills or Subagents? → `03-skills-vs-subagents-decision-tree.md`
+- Conceptual differences → `02-skills-vs-subagents-comparison.md`
+
+**For Strategic Context:**
+- Why Skills exist → `01-why-skills-exist.md`
+- Real-world validation → `case-studies.md`
+
+---
+
+**FILE END - Estimated Token Count: ~2,500 tokens (~218 lines)**

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