@rfxlamia/skillkit 1.0.0 → 1.2.0

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

package/skills/skills/skillkit-help/knowledge/foundation/08-when-not-to-use-skills.md

@@ -0,0 +1,270 @@
+---
+title: "When NOT to Use Skills: Red Flags & Alternatives"
+purpose: "Avoiding inappropriate Skills usage, recognizing red flags"
+token_estimate: "1500"
+read_priority: "medium"
+read_when:
+  - "User considering Skills adoption"
+  - "ROI evaluation"
+  - "User describes low-frequency use case"
+  - "User has simple requirements"
+  - "User lacks technical resources"
+  - "Complement to 01-why-skills-exist"
+related_files:
+  must_read_first:
+    - "01-why-skills-exist.md"
+  read_together:
+    - "03-skills-vs-subagents-decision-tree.md"
+  read_next: []
+avoid_reading_when:
+  - "User already committed to Skills"
+  - "User has clear high-value use case"
+  - "During implementation phase"
+last_updated: "2025-11-01"
+---
+
+# When NOT to Use Skills: Red Flags & Alternatives
+
+## I. INTRODUCTION
+
+Skills are powerful but not appropriate for all situations. Understanding when NOT to use Skills prevents wasted effort, reduces scope creep, and helps identify better alternatives.
+
+**Core Principle:** Skills excel for repeatable, well-defined workflows with technical teams. If use case doesn't match this profile, consider alternatives first.
+
+**This File Helps:** Identify red flags indicating Skills are inappropriate, evaluate ROI realistically, choose better-suited alternatives.
+
+**Complement to:** `01-why-skills-exist.md` (benefits) and `03-skills-vs-subagents-decision-tree.md` (alternatives).
+
+---
+
+## II. 5 SCENARIOS WHERE SKILLS ARE INAPPROPRIATE
+
+### Scenario A: One-Time or Rare Tasks
+
+**Description:** Task needed once or very infrequently (annually, ad-hoc).
+
+**Why Inappropriate:**
+- Setup overhead (2-4 hours) not justified by single use
+- No benefit from reusability (Skills' main value)
+- Maintenance burden for unused skill
+- Token overhead without return
+
+**Example:** "Create year-end report once" - Direct prompting faster than building skill.
+
+**Red Flags:**
+- Phrases: "just this once", "one-time project", "annual task"
+- No similar future tasks planned
+- Custom requirements unlikely to repeat
+
+**Better Alternative:** Use direct prompting with clear instructions. Save conversation for reference if needed yearly.
+
+**ROI Calculation:** Setup cost 3 hours. If used 1×/year, payback never occurs. Direct prompting: 15 minutes per use, far more efficient.
+
+---
+
+### Scenario B: Non-Technical Teams Without Support
+
+**Description:** Team lacks technical skills (coding, Git, file organization) and no technical support available.
+
+**Why Inappropriate:**
+- Steep learning curve (comfort with file structures, YAML, scripting)
+- Manual distribution requires coordination skills
+- Troubleshooting needs technical expertise
+- Version control challenges without Git knowledge
+
+**Example:** Marketing team wants brand guidelines skill but has no developers. Manual upload + coordination becomes bottleneck.
+
+**Red Flags:**
+- Team has no programmers or technical members
+- Unfamiliar with Git, YAML, command line
+- Struggle with basic file organization
+- No IT support available
+
+**Better Alternative:** Use Custom Instructions for brand guidelines. Use Projects for persistent context. Both are UI-based, no technical skills required.
+
+**Support Requirement:** Minimum one technical person per 10-person team, or dedicated IT support for skill management.
+
+---
+
+### Scenario C: Rapidly Changing Requirements
+
+**Description:** Workflows, procedures, or standards change frequently (weekly/monthly).
+
+**Why Inappropriate:**
+- Constant skill updates required
+- Version synchronization overhead
+- Testing burden after each change
+- Team coordination costs multiply
+
+**Example:** Startup with evolving product development process. Procedures change weekly - skill becomes maintenance burden.
+
+**Red Flags:**
+- Phrases: "we're still figuring this out", "process in flux"
+- Organizational changes underway
+- Experimental workflows
+- No stable procedures yet
+
+**Better Alternative:** Use Projects to capture evolving context. Once stabilized (3-6 months unchanged), consider converting to Skill.
+
+**Stability Threshold:** Wait until procedures unchanged for 2-3 months before investing in skill creation.
+
+---
+
+### Scenario D: Low-Frequency Use Cases
+
+**Description:** Task occurs monthly or less frequently, low business impact.
+
+**Why Inappropriate:**
+- Token overhead (30-50 tokens always loaded) not justified
+- Maintenance effort exceeds usage value
+- Skills designed for frequent, high-value tasks
+- ROI negative at low frequency
+
+**Example:** "Format monthly newsletter" (1×/month, 10 minutes task) - skill overhead not worth automation.
+
+**Red Flags:**
+- Usage frequency: <4× per month
+- Task completion time: <30 minutes
+- Low business criticality
+- Alternatives readily available
+
+**Better Alternative:** Create reusable prompt template in Projects or shared document. Use when needed without skill overhead.
+
+**Frequency Threshold:** Skills justify investment when used 10+ times/month or task saves 1+ hours each time.
+
+---
+
+### Scenario E: Highly Sensitive Data Without Security Resources
+
+**Description:** Working with restricted data (financial, health, legal) without security expertise to audit skills.
+
+**Why Inappropriate:**
+- Third-party skills pose security risks (prompt injection, code execution, data exfiltration)
+- Comprehensive auditing requires security expertise
+- Compliance requirements (GDPR, HIPAA, SOX) demand rigorous vetting
+- Risk exposure exceeds automation benefit
+
+**Example:** Law firm wants contract analysis skill using community skill. HIPAA compliance requires security audit they can't perform.
+
+**Red Flags:**
+- Sensitive data: PII, financial, health records, legal documents
+- No security team available
+- Considering third-party/community skills
+- Compliance requirements (GDPR, HIPAA, SOX)
+
+**Better Alternative:** Use official Anthropic skills only (PowerPoint, Excel, Word, PDF) - these are vetted. Or use Projects with Custom Instructions (no code execution risk).
+
+**Security Requirement:** Comprehensive security audit mandatory for third-party skills with sensitive data. Only proceed if security expertise available.
+
+---
+
+## III. RED FLAGS CHECKLIST
+
+**Evaluate Your Use Case - If 3+ Apply, Reconsider Skills:**
+
+- [ ] Task needed <4 times per month
+- [ ] Task takes <30 minutes to complete manually
+- [ ] One-time or annual occurrence
+- [ ] Workflows still evolving or experimental
+- [ ] Team lacks technical skills (no programmers)
+- [ ] No version control knowledge (Git unfamiliar)
+- [ ] Working with highly sensitive data AND no security resources
+- [ ] Considering third-party skills for compliance-regulated data
+- [ ] No clear ROI calculation possible
+- [ ] Setup investment (3-5 hours) not justified by savings
+- [ ] Simpler alternatives exist (Projects, Custom Instructions)
+- [ ] Enterprise deployment needed but not available
+- [ ] Rapid changes expected in procedures
+
+**Scoring:** 0-2 flags: Skills likely appropriate. 3-4 flags: Consider alternatives. 5+ flags: Skills inappropriate.
+
+---
+
+## IV. DECISION MATRIX
+
+**Skills vs. Alternatives - Quick Reference:**
+
+| Situation | Use Skills | Use Projects | Use Custom Instructions | Use Direct Prompting |
+|-----------|------------|--------------|-------------------------|----------------------|
+| **Frequency** | 10+/month | Ongoing work | Every conversation | One-time/rare |
+| **Stability** | Stable (unchanged 3+ months) | Evolving | Stable preferences | Ad-hoc |
+| **Technical Skills** | Team has developers | Any skill level | Any skill level | Any skill level |
+| **Reusability** | High (across contexts) | Project-specific | Universal | No reuse |
+| **Setup Time** | 3-5 hours justified | 15-30 min | 5-10 min | None |
+| **Context Needs** | Procedural "how-to" | Accumulated context | Style/tone | Specific request |
+| **Team Size** | 3+ people sharing | Individual or small team | Individual | Individual |
+| **Data Sensitivity** | Public/Internal (audited) | Any | Any | Any |
+
+**Decision Flow:**
+1. Check frequency → If <4×/month → Not Skills
+2. Check stability → If changing weekly → Not Skills
+3. Check technical capability → If non-technical team → Not Skills
+4. Check ROI → If setup > savings → Not Skills
+5. Check alternatives → If simpler option works → Use alternative
+
+---
+
+## V. ALTERNATIVES SUMMARY
+
+**When Skills Don't Fit:**
+
+**Projects (Persistent Context):**
+- Best for: Ongoing work, evolving requirements, accumulated context
+- No technical skills required
+- Context persists across conversations
+- Example: Campaign planning, research projects
+
+**Custom Instructions (Universal Preferences):**
+- Best for: Universal preferences, tone/style, general directives
+- Applies to all conversations automatically
+- No setup complexity
+- Example: Writing style, communication preferences
+
+**Direct Prompting (Ad-Hoc Tasks):**
+- Best for: One-time tasks, rare occurrences, exploratory work
+- Zero setup time
+- Maximum flexibility
+- Example: Annual reports, one-off analysis
+
+**Subagents (Complex Workflows):**
+- Best for: Multi-step reasoning, specialized expertise, isolated context
+- Higher token cost but capability justifies
+- No filesystem dependency
+- Example: Code review, security audits
+
+**MCP (External Data Access):**
+- Best for: Real-time data, database queries, API integrations
+- Complements Skills well
+- No procedural knowledge captured
+- Example: Customer database queries
+
+**Combination Approaches:**
+- Start with Projects to capture evolving workflows
+- After stabilization (3-6 months), convert to Skills
+- Use Custom Instructions + Projects for common pattern
+- Add Skills only when reusability clear
+
+**Migration Path:** Projects → Skills (when workflows stabilize), Custom Instructions → Skills (when procedures formalize).
+
+---
+
+## WHEN TO READ NEXT
+
+**Before Skills Adoption:**
+- Understand benefits → `01-why-skills-exist.md`
+- Compare approaches → `02-skills-vs-subagents-comparison.md`
+- Use decision framework → `03-skills-vs-subagents-decision-tree.md`
+
+**For Implementation:**
+- Cost analysis → `05-token-economics.md`
+- Platform constraints → `06-platform-constraints.md`
+- Security review → `07-security-concerns.md`
+
+**If Skills Appropriate:**
+- Skip to implementation guides
+- Start small (3-5 workflows)
+- Measure ROI continuously
+
+---
+
+**FILE END - Estimated Token Count: ~1,500 tokens (~215 lines)**

package/skills/skills/skillkit-help/template/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: your-skill-name
+description: >
+  One sentence: what this skill does and when to invoke it.
+  Use for: [list 2-3 trigger phrases users would naturally type].
+category: engineering
+# Available categories: core, engineering, documentation, planning,
+# deployment, productivity, quality, security, experimentation,
+# agent-frameworks, creative
+---
+
+## Overview
+
+[2-3 sentences: what this skill does and why it exists. Be specific.
+Bad: "Helps with code." Good: "Reviews Python functions for PEP-8
+compliance and common anti-patterns, then outputs a prioritized fix list."]
+
+---
+
+## When to Use This Skill
+
+[Optional but recommended for complex skills. List the specific
+conditions that should trigger this skill.]
+
+Examples:
+- User pastes a function and asks for a review
+- User says "check my code" or "code review"
+
+---
+
+## Section 1: [First Major Step]
+
+[Instructions for the agent. Be explicit — don't say "do the right thing,"
+say exactly what to do. Use numbered steps for ordered workflows,
+bullet points for flexible guidance.]
+
+1. Step one
+2. Step two
+3. Step three
+
+---
+
+## Section 2: [Second Major Step]
+
+[Continue as needed. Each section should have one clear responsibility.]
+
+---
+
+## Reference: [Optional — Load-on-Demand Content]
+
+[Put bulky reference material here rather than in the main flow.
+The agent loads this only when needed, saving tokens.]