@rfxlamia/skillkit 1.0.0 → 1.2.0

package/skills/skills/skillkit/knowledge/application/10-technical-architecture.md

@@ -0,0 +1,324 @@
+---
+title: "Technical Architecture Deep Dive: How Skills Actually Work"
+purpose: "Detailed mechanics of progressive disclosure, runtime, and platform differences"
+token_estimate: "2500"
+read_priority: "medium"
+read_when:
+  - "User asking 'How does progressive disclosure work technically?'"
+  - "User needs implementation details"
+  - "Debugging loading issues"
+  - "Understanding platform differences"
+  - "Advanced implementation planning"
+related_files:
+  must_read_first:
+    - "01-why-skills-exist.md"
+    - "02-skills-vs-subagents-comparison.md"
+  read_together:
+    - "05-token-economics.md"
+    - "06-platform-constraints.md"
+  read_next:
+    - "12-testing-and-validation.md"
+avoid_reading_when:
+  - "User just learning concepts (too technical)"
+  - "User not implementing yet"
+  - "Simple use case (unnecessary detail)"
+last_updated: "2025-11-03"
+---
+
+# Technical Architecture Deep Dive: How Skills Actually Work
+
+## I. INTRODUCTION
+
+**Scope:** Technical mechanics of progressive disclosure, runtime environment, and platform-specific implementation details.
+
+**Prerequisites:** Basic understanding of Skills concepts (`01-why-skills-exist.md`), Skills vs Subagents distinctions (`02-skills-vs-subagents-comparison.md`).
+
+**What This Covers:** Step-by-step loading process, context window management, execution environment, platform differences (Claude.ai vs API vs Code).
+
+**What This Does NOT Cover:** Platform limitations and deployment challenges (see `06-platform-constraints.md`), security risks (see `07-security-concerns.md`).
+
+---
+
+## II. PROGRESSIVE DISCLOSURE MECHANICS
+
+### A. Three-Level Loading Architecture
+
+Progressive disclosure is the core design principle that makes Skills flexible and scalable. The system works through three hierarchical levels:
+
+| Level | Component | Size | When Loaded | Token Cost |
+|-------|-----------|------|-------------|------------|
+| **1** | Metadata (name, description) | ~100 tokens | Startup | Always |
+| **2** | SKILL.md body | 800-3,000 tokens | When triggered | On-demand |
+| **3** | Resources (docs, scripts) | Variable | When needed | Zero until used |
+
+**Key Efficiency:** 50 skills = 5,000 tokens at startup. Scripts execute WITHOUT loading code—only output consumes tokens.
+
+### B. Loading Process Flow
+
+**Example:** User requests "Extract text from this PDF"
+
+```
+STARTUP: System prompt includes all skill descriptions (~5,000 tokens)
+QUERY: Claude evaluates PDF Processing skill as relevant
+LOAD: bash: read /mnt/skills/pdf-skill/SKILL.md (800 tokens)
+DECISION: Form filling not needed → FORMS.md NOT loaded (0 tokens)
+EXECUTE: Uses SKILL.md guidance for task
+```
+
+**Total tokens:** 5,800 (startup + active skill) vs 150,000+ all-in-context approach.
+
+### C. Context Window Management
+
+**Context Allocation:**
+
+| Component | Token Budget | Priority |
+|-----------|--------------|----------|
+| User conversation | 40,000-60,000 | Highest |
+| Active skill instructions | 800-5,000 | High |
+| Skill metadata (all) | ~5,000 | Medium |
+| System prompt | 10,000-15,000 | Critical |
+
+**Multi-Skill Coordination:** Each skill loads independently. When multiple skills active: Conversation + Skill A + Skill B + Skill C instructions share context window. Example: PDF (800) + Excel (1,200) + Word (1,000) = 3,000 tokens total.
+
+### D. Optimization Techniques
+
+**1. Metadata Engineering:**
+```yaml
+# BAD: Vague (triggers unnecessarily)
+description: "Helps with files"
+
+# GOOD: Specific (reduces false activation)
+description: "Extract text/tables from PDFs, fill forms, merge documents"
+```
+
+**2. Reference File Splitting:**
+```
+skill/
+  SKILL.md           # Core (800 tokens)
+  ADVANCED.md        # Complex scenarios (load when needed)
+  scripts/validate.py  # Execute, not load
+```
+
+**3. Script Output Minimization:**
+```python
+# BAD: Verbose (4 lines)
+print(f"Processing: {filename}")
+print(f"Extracting...")
+print(f"Found {len(text)} chars")
+print(f"Done!")
+
+# GOOD: Essential only (1 line)
+print(f"Extracted {len(text)} chars from {filename}")
+```
+
+---
+
+## III. RUNTIME ENVIRONMENT
+
+### A. Execution Container
+
+**VM Specifications:**
+
+| Specification | Value | Implication |
+|---------------|-------|-------------|
+| Container Type | Sandboxed VM | Isolated execution |
+| Filesystem Access | Full `/home/claude` | Read/write capable |
+| Code Execution | Python, Bash, Node.js | Multi-language |
+| Network | Limited | See platform docs |
+| Resource Limits | Platform-dependent | Varies |
+
+**Filesystem Scope:**
+- `/home/claude/` - Working directory (full access)
+- `/mnt/skills/` - Skill files (read-only)
+- `/mnt/user-data/uploads/` - User files (read-only)
+- `/mnt/user-data/outputs/` - Output delivery (write access)
+
+**Security Boundaries:** Skills CANNOT access other skills' files, modify system files, or access other conversations. **For security details, see:** `07-security-concerns.md`
+
+### B. Tool Access & Permissions
+
+**Permission Models:**
+
+| Context | Permission Model | Inheritance |
+|---------|------------------|-------------|
+| **Skills** | Inherit from user | Yes - full tools available |
+| **Subagents** | Explicitly granted | No - must specify each |
+
+**Example:**
+```yaml
+# Skills automatically inherit ALL user tools
+allowed-tools: [bash_tool, view, create_file]
+
+# Subagents must list explicitly
+subagent.tools = ["bash_tool", "web_search"]
+```
+
+### C. Code Execution
+
+**Supported Languages:**
+
+| Language | Execution | Package Mgmt | Use Cases |
+|----------|-----------|--------------|-----------|
+| Python | Native | pip, conda | Data, ML, APIs |
+| Bash | Native | apt, brew | File ops, system |
+| Node.js | Native | npm | Web scraping |
+
+**Execution Pattern:**
+```python
+# Skills execute code WITHOUT loading to context
+result = subprocess.run(['python', 'process.py'], capture_output=True)
+print(result.stdout)  # Only output consumes tokens
+```
+
+### D. Network & External Access
+
+| Platform | Web Access | API Calls | Rate Limits |
+|----------|------------|-----------|-------------|
+| Claude.ai | Via `web_search` | Yes | Platform limits |
+| API | Via `web_search` | Yes | User/org limits |
+| Claude Code | Direct network | Yes | None |
+
+**For detailed constraints, see:** `06-platform-constraints.md` Section III
+
+---
+
+## IV. PLATFORM DIFFERENCES
+
+### A. Claude.ai Web/Desktop
+
+**Deployment:**
+```
+Settings → Capabilities → Skills → Upload ZIP
+Limit: 20 skills per user
+```
+
+| Feature | Specification |
+|---------|---------------|
+| Container | Sandboxed VM |
+| Filesystem | `/home/claude` read/write |
+| Code | Python, Bash, Node pre-installed |
+| Network | `web_search` only |
+| Updates | Manual re-upload required |
+
+**Best Practices:** Keep ≤20 skills, use progressive disclosure, version control via Git (manual sync).
+
+### B. Claude API
+
+**Deployment:**
+```python
+client = Anthropic(api_key="...")
+skill = client.skills.create(
+    name="my-skill",
+    files=[("SKILL.md", content)]
+)
+```
+
+| Feature | Specification |
+|---------|---------------|
+| Container | Sandboxed VM |
+| Filesystem | `/mnt/skills/` read-only |
+| Code | Full capabilities |
+| Network | Full access |
+| Updates | Programmatic `skills.update()` |
+
+**API-Specific Features:**
+
+**Programmatic Management:**
+```python
+skill = client.skills.create(...)       # Create
+client.skills.update(skill_id, ...)     # Update
+client.skills.delete(skill_id)          # Delete
+skills = client.skills.list()           # List
+```
+
+**Dynamic Loading:**
+```python
+response = client.messages.create(
+    skills=[skill.id],  # Reference by ID
+    messages=[...]
+)
+```
+
+**No 20-skill limit.** Metadata loaded per-conversation (not globally).
+
+### C. Claude Code CLI
+
+**Deployment:**
+```bash
+# Personal skills
+~/.claude/skills/my-skill/SKILL.md
+
+# Project skills
+.claude/skills/my-skill/SKILL.md
+```
+
+| Feature | Specification |
+|---------|---------------|
+| Container | Direct filesystem (no sandbox) |
+| Filesystem | Full system access |
+| Code | Native execution all languages |
+| Network | Full access unrestricted |
+| Updates | Instant file editing |
+
+**Unique Advantages:**
+
+**1. Direct Editing:**
+```bash
+vim ~/.claude/skills/my-skill/SKILL.md  # Changes instant
+```
+
+**2. Git Integration:**
+```bash
+cd ~/.claude/skills/my-skill
+git init && git commit -m "Initial"
+```
+
+**3. Project-Specific Skills:**
+```
+project/.claude/skills/  # Only available in this project
+```
+
+**Development Workflow:**
+```bash
+mkdir -p ~/.claude/skills/my-skill
+vim ~/.claude/skills/my-skill/SKILL.md
+claude chat "test skill"  # Test immediately
+```
+
+### D. Platform Selection Guide
+
+| Use Case | Recommended | Reason |
+|----------|-------------|--------|
+| Individual productivity | Claude.ai/Desktop | Easy setup |
+| Rapid development | Claude Code | Instant testing |
+| Production | API | Scalability, control |
+| Team collaboration | API + Git | Version control |
+| Enterprise | API | Automation, security |
+
+**Migration Paths:**
+
+```
+Claude.ai → Claude Code: Export ZIP, unzip to ~/.claude/skills/
+Claude Code → API: Read SKILL.md, upload via client.skills.create()
+API → Claude.ai: Download files, create ZIP, upload via UI
+```
+
+---
+
+## V. KEY TAKEAWAYS
+
+**Progressive Disclosure Benefits:**
+
+Three-level loading architecture (metadata → SKILL.md → resources) enables massive scalability without context window pressure. Unused skills cost zero tokens at runtime. Scripts execute without loading code—only output consumes tokens. This design allows unlimited skill installations with minimal startup overhead.
+
+**Platform-Aware Design:**
+
+Core architecture remains consistent: progressive disclosure, SKILL.md structure, YAML frontmatter work identically across platforms. Platform differences affect deployment only—not skill design. Choose based on needs: Claude.ai for individual productivity, API for programmatic control and scale, Claude Code for rapid development and Git workflows.
+
+**Next Steps:**
+
+Implementation guidance → `12-testing-and-validation.md` for testing methodology. Token optimization → `05-token-economics.md` for efficiency patterns. Platform constraints → `06-platform-constraints.md` for deployment limits. Security boundaries → `07-security-concerns.md` for risk assessment.
+
+---
+
+**End of File 10**

package/skills/skills/skillkit/knowledge/application/11-adoption-strategy.md

@@ -0,0 +1,267 @@
+---
+title: "Adoption Strategy: Rolling Out Skills to Teams"
+purpose: "Strategic approach for organizational Skills adoption"
+token_estimate: "2000"
+read_priority: "high"
+read_when:
+  - "Planning Skills rollout to team/organization"
+  - "User asking 'How do we deploy this to our team?'"
+  - "Coordination across multiple users needed"
+  - "Version control and governance questions"
+  - "Measuring Skills ROI and success"
+related_files:
+  must_read_first:
+    - "01-why-skills-exist.md"
+  read_together:
+    - "09-case-studies.md"
+    - "06-platform-constraints.md"
+  read_next:
+    - "12-testing-and-validation.md"
+avoid_reading_when:
+  - "Individual use only (not team deployment)"
+  - "Just learning concepts"
+  - "Not ready for implementation"
+last_updated: "2025-11-03"
+---
+
+# Adoption Strategy: Rolling Out Skills to Teams
+
+## I. INTRODUCTION
+
+**Why This Matters:** Skills adoption fails from poor rollout strategy, NOT technical issues. Common failures: premature scaling, no metrics, version chaos, lack of stakeholder buy-in.
+
+**Critical Success Factors:** Start small (3-5 workflows), measure quantitatively, version control BEFORE scaling, iterate on real data.
+
+**Scope:** Pilot methodology, evaluation frameworks, organizational rollout. **For detailed testing:** `12-testing-and-validation.md`. **For platform mechanics:** `06-platform-constraints.md`.
+
+---
+
+## II. START SMALL METHODOLOGY
+
+### A. Phase 1: Pilot (2-4 Weeks)
+
+**Pilot Parameters:**
+
+| Parameter | Specification | Rationale |
+|-----------|---------------|-----------|
+| Workflows | 3-5 high-value | Focus proven patterns |
+| Team Size | 5-10 people | Easy coordination |
+| Timeline | 2-4 weeks | Quick feedback |
+| Success Metrics | 2-3 quantitative KPIs | Clear measurement |
+
+**Workflow Selection Criteria:** High-value (≥2 hrs/week per person), well-understood (documented process), measurable (before/after comparison), low-risk (non-critical), frequent (daily/weekly).
+
+**Pilot Checklist:**
+
+| Task | Owner | Timeline |
+|------|-------|----------|
+| Identify workflows | Team Lead | Week 0 |
+| Establish baselines | Analyst | Week 0 |
+| Create test scenarios | Technical Lead | Week 1 |
+| Develop Skills | Developer | Week 1-2 |
+| Deploy to pilot | DevOps | Week 2 |
+| Collect data | All | Week 2-4 |
+| Analyze results | Analyst | Week 4 |
+
+### B. Phase 2: Validate (2 Weeks)
+
+**Validation Metrics:**
+
+| Metric | Measurement | Target |
+|--------|-------------|--------|
+| Time Savings | Before/after duration | ≥50% reduction |
+| Error Rate | Mistakes per 100 tasks | ≥30% reduction |
+| Adoption | % team using | ≥80% usage |
+| Satisfaction | User survey (1-10) | ≥7/10 average |
+
+**Data Collection:** Time tracking (manual vs Skills-assisted), error counts (pre vs post), usage logs (frequency, success rate), user surveys (what worked, what didn't).
+
+**Iteration Loop:** Collect Data → Analyze → Identify Gaps → Update Skills → Redeploy → Measure Again.
+
+**Expansion Criteria:** Time savings ≥50% + Satisfaction ≥7/10 + Adoption ≥80% + Zero critical failures.
+
+### C. Phase 3: Expand (4-8 Weeks)
+
+**Expansion Timeline:**
+
+| Week | Activity | Teams | Checkpoint |
+|------|----------|-------|------------|
+| 1-2 | Document lessons | Pilot | Handoff ready |
+| 2-3 | Train champions | 2-3 additional | Champions certified |
+| 3-4 | Deploy 2nd wave | 2-3 teams | Metrics tracked |
+| 5-8 | Organization-wide | Remaining | Version stable |
+
+**Rollout Patterns:** Conservative (Pilot → 2-3 teams → 5-10 teams → Full, 12-16 weeks) vs Aggressive (Pilot → 5-10 teams → Full, 8-12 weeks).
+
+**Pause Signals:** ❌ Satisfaction <6/10, critical failures >1/week, support overwhelmed, version drift.
+
+---
+
+## III. TWO CLAUDE DEVELOPMENT METHOD
+
+### A. The Pattern
+
+**Core Concept:** Use two separate Claude instances—Designer (Claude A) and Tester (Claude B)—to eliminate bias and observe real behavior.
+
+| Role | Purpose | Why |
+|------|---------|-----|
+| **Claude A** | Design Skills | Knows intent (biased) |
+| **Claude B** | Test Skills | Doesn't know intent (unbiased) |
+
+**Value:** Claude B's unbiased behavior reveals actual skill quality, not assumptions.
+
+### B. Implementation
+
+**5-Step Process:**
+
+1. **Setup:** Open two tabs—Claude A (designer) and Claude B (tester with Skills enabled)
+2. **Design:** Prompt Claude A: "Design Skill for [workflow]" → Export SKILL.md
+3. **Deploy:** Upload Skill to Claude B (Settings → Skills OR `~/.claude/skills/`)
+4. **Test:** Prompt Claude B: "Help me [task]" → Observe: Does it trigger? Follow workflow? Handle edges?
+5. **Iterate:** Return to Claude A with gaps: "Claude B did X, should do Y. Fix?" → Redeploy
+
+**Example Iteration:**
+- Iteration 1: Doesn't trigger → Fix YAML description
+- Iteration 2: Triggers but wrong workflow → Clarify SKILL.md steps
+- Iteration 3: Fails edge case → Add examples
+- Iteration 4: Works reliably → Deploy to pilot
+
+### C. Tips
+
+**Maximize Effectiveness:** Don't tell Claude B about Skill (natural discovery), use realistic tasks (not toy problems), document struggles, iterate 3-5 times, test edge cases explicitly.
+
+---
+
+## IV. EVALUATION FRAMEWORKS
+
+### A. Success Metrics
+
+**Quantitative:**
+
+| Metric | Measurement | Target | Frequency |
+|--------|-------------|--------|-----------|
+| Time Savings | Task duration | ≥50% reduction | Weekly |
+| Error Rate | Mistakes/100 tasks | ≥30% reduction | Weekly |
+| Usage Rate | % team using | ≥80% adoption | Daily |
+| Success Rate | % completed correctly | ≥90% success | Daily |
+
+**Qualitative:** User satisfaction (≥7/10), perceived value (≥85% would keep using), skill quality (≥8/10 helpful).
+
+**ROI Example:**
+```
+Cost: $800 development + $100 training = $900/person
+Savings: 10 hrs/month @ $50/hr = $500/month
+Payback: 1.8 months | Annual ROI: 567%
+```
+
+### B. Testing Scenarios
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| Positive | Should succeed | "Generate Q3 report" → Activates |
+| Negative | Should NOT trigger | "Tell joke" → Doesn't activate |
+| Edge Cases | Boundaries | Empty data → Handles gracefully |
+| Integration | Multi-skill | PDF + Excel → Both work |
+
+**For detailed testing procedures:** `12-testing-and-validation.md`
+
+### C. Baseline Establishment
+
+**Pre-Skills (Critical):** Measure 10+ task instances, calculate mean/std dev, document process, identify pain points.
+
+**Post-Skills:** Same tasks WITH Skills, compare metrics (time, quality, consistency), test statistical significance (p < 0.05), document improvements.
+
+**Example:**
+```
+Task: PDF → Word conversion
+Baseline (n=12): 45 min ± 12 min, 15% errors
+Post-Skills (n=12): 8 min ± 2 min, 2% errors
+Result: 82% time reduction, p < 0.01 → Deploy
+```
+
+### D. Continuous Monitoring
+
+| Metric | Tool | Alert |
+|--------|------|-------|
+| Usage | Logs | <50% usage (investigate) |
+| Errors | Tracker | >10% failures (fix) |
+| Complaints | Tickets | >5/week (prioritize) |
+| Version drift | Git audit | Multiple versions (consolidate) |
+
+---
+
+## V. ORGANIZATIONAL ROLLOUT
+
+### A. Stakeholder Management
+
+| Role | Responsibilities | Success Criteria |
+|------|-----------------|------------------|
+| Executive Sponsor | Budget, messaging | Visible support |
+| Team Champions | Advocacy, feedback | ≥2/team, active |
+| Technical Lead | Development, quality | Meets standards |
+| Support Lead | Training, troubleshooting | <24hr response |
+
+**Communication:** Executives (monthly ROI), Champions (weekly sync), Users (bi-weekly tips), Technical (daily collaboration).
+
+### B. Version Control & Governance
+
+**Git Structure:**
+```
+skills-repo/
+  README.md, CHANGELOG.md
+  skills/skill-name/
+    SKILL.md
+    VERSION (1.0.0)
+```
+
+**Semantic Versioning:**
+
+| Change | Version | Example |
+|--------|---------|---------|
+| Breaking | MAJOR (2.0.0) | YAML structure change |
+| Features | MINOR (1.1.0) | New workflow |
+| Fixes | PATCH (1.0.1) | Bug fix |
+
+**Governance:** Proposal (Technical Lead, 1 day) → Development (2 peer reviews, 2-3 days) → Testing (QA, 3-5 days) → Deployment (Executive approval for major, 1 day).
+
+**Change Process:** Create branch → Develop → PR → 2 approvals → Merge → Tag release → Update CHANGELOG → Notify team.
+
+### C. Distribution
+
+| Platform | Method | Pros | Cons |
+|----------|--------|------|------|
+| Claude.ai | Manual ZIP upload | Simple | Version drift risk |
+| API | Programmatic | Automated | Requires API |
+| Claude Code | Git clone | Version control | Manual git pull |
+
+**Recommended (Team ≥10):** Git repository (primary) + platform-specific deployment (Claude.ai manual, API automated, Code git clone).
+
+### D. Common Challenges
+
+| Challenge | Solution |
+|-----------|----------|
+| Version Drift | Quarterly audits, update reminders |
+| Skill Discovery | Internal catalog, better YAML descriptions |
+| Security | Mandatory review, minimal permissions (**See:** `07-security-concerns.md`) |
+
+---
+
+## VI. KEY TAKEAWAYS
+
+**Adoption Principles:** Start small with focused pilots, measure quantitatively against baselines, implement version control before scaling, iterate on real data. Avoid premature scaling, metric-free rollouts, and version chaos.
+
+**Timeline Expectations:**
+
+| Phase | Conservative | Aggressive |
+|-------|--------------|------------|
+| Pilot → Validation | 6 weeks | 4 weeks |
+| Expansion | +12 weeks | +6 weeks |
+| **Total to Org-Wide** | **18 weeks** | **10 weeks** |
+
+**Success Indicators:** Satisfaction ≥7/10, adoption ≥80%, time savings ≥50%, zero critical failures. Red flags: satisfaction <6/10, usage <50%, unclear ROI.
+
+**Next Steps:** Pilot checklist → Section II.A. Baseline methodology → Section IV.C. Version control → Section V.B. Testing procedures → `12-testing-and-validation.md`.
+
+---
+
+**End of File 11**