@rfxlamia/skillkit 1.0.0 → 1.2.0

package/skills/skills/skillkit/knowledge/tools/14-validation-tools-guide.md

@@ -0,0 +1,150 @@
+---
+title: "Validation Tools: Usage Guide"
+purpose: "Quick start for validate_skill.py automation"
+token_estimate: "800"
+read_priority: "high"
+read_when: ["Before skill deployment", "CI/CD setup", "Quality checks"]
+related_files:
+  concepts: ["02-description-patterns", "07-security", "10-architecture", "12-validation-theory"]
+  tools: ["validate_skill.py", "security_scanner.py", "token_estimator.py"]
+last_updated: "2025-11-05"
+---
+
+# Validation Tools: Quick Start
+
+## Overview
+
+`validate_skill.py` automates 8 quality checks, catches issues early (saves 2-4 hours), zero token cost.
+
+**Theory:** File 12. **This guide:** Usage only.
+
+---
+
+## Installation
+
+### Using Virtual Environment (Recommended)
+
+```bash
+cd ~/.claude/skills/skillkit
+source venv/bin/activate
+python scripts/validate_skill.py --help
+```
+
+### Without Virtual Environment
+
+```bash
+pip install pyyaml
+python3 /path/to/skillkit/scripts/validate_skill.py --help
+```
+
+---
+
+## Basic Usage
+
+> **Note:** Make sure venv is activated: `source venv/bin/activate`
+
+```bash
+python scripts/validate_skill.py <skill_path> [--strict] [--format text|json]
+```
+
+**Example:**
+```bash
+# With venv activated
+python scripts/validate_skill.py ./my-skill/
+
+# Full path without venv
+python3 "$HOME/.claude/skills/skillkit/scripts/validate_skill.py" ./my-skill/
+```
+
+**Output:**
+```
+✓ YAML Frontmatter
+✓ File Structure
+âš  Description Quality (missing trigger)
+✓ Token Efficiency (347 lines)
+✓ Security Basics
+✓ Writing Style
+✓ Progressive Disclosure
+✓ Cross-References
+
+Score: 7/8 (1 warning)
+```
+
+**Exit Codes:** 0=pass, 1=warnings, 2=failures
+
+---
+
+## Workflows
+
+**Pre-Deployment:** `python3 validate_skill.py ./my-skill/` → Fix issues → Re-validate until 8/8
+
+**Fixes:** Description (File 02) | Tokens (File 10) | Security (File 07)
+
+**CI/CD:** `source venv/bin/activate && python scripts/validate_skill.py ./my-skill/ --strict --format json; exit $?`
+
+**Batch:** `source venv/bin/activate && for skill in skills/*/; do python scripts/validate_skill.py "$skill" --strict; done`
+
+---
+
+## Validation Checks
+
+| Check | Validates | Reference |
+|-------|-----------|-----------|
+| YAML | Valid syntax, required fields | File 02 |
+| Structure | SKILL.md, scripts/, references/ | File 10 |
+| Description | WHAT + WHEN triggers | File 02 |
+| Tokens | <500 lines, <5000 tokens | File 05 |
+| Security | No secrets, safe patterns | File 07 |
+| Style | Imperative, scannable | All files |
+| Disclosure | Proper splits, TOCs | File 10 |
+| References | No broken links | Phase 1-2 |
+
+**Note:** Use `security_scanner.py` for comprehensive audit (File 16).
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "SKILL.md not found" | `ls my-skill/SKILL.md` - verify path |
+| "YAML invalid" | Check `---` markers, File 02 format |
+| "Module yaml not found" | Activate venv: `source venv/bin/activate` or install: `pip install pyyaml` |
+| Many warnings | Run without `--strict` first, fix failures, then enable |
+
+---
+
+## Toolchain Integration
+
+```bash
+validate_skill.py → security_scanner.py → token_estimator.py → deploy
+```
+
+**Best Practices:**
+- ✅ Validate before `package_skill.py`
+- ✅ Use `--strict` in CI/CD
+- ✅ Fix all failures before deploy
+- ✅ Validate frequently during dev
+
+---
+
+## Quick Reference
+
+```bash
+# Make sure venv is active first
+source venv/bin/activate
+
+# Standard
+python scripts/validate_skill.py ./my-skill/
+
+# Strict (CI)
+python scripts/validate_skill.py ./my-skill/ --strict
+
+# JSON output
+python scripts/validate_skill.py ./my-skill/ --format json
+
+# Full path (tanpa venv)
+python3 "$HOME/.claude/skills/skillkit/scripts/validate_skill.py" ./my-skill/
+```
+
+**Next:** security_scanner.py (File 16) → token_estimator.py (File 15)

package/skills/skills/skillkit/knowledge/tools/15-cost-tools-guide.md

@@ -0,0 +1,157 @@
+---
+title: "Cost Tools: Token Estimation Guide"
+purpose: "Quick start for token_estimator.py automation"
+token_estimate: "800"
+read_priority: "high"
+read_when: ["Cost analysis needed", "Progressive disclosure planning", "Budget optimization"]
+related_files:
+  concepts: ["05-token-economics", "10-progressive-architecture", "15-cost-optimization"]
+  tools: ["token_estimator.py", "validate_skill.py"]
+last_updated: "2025-11-05"
+---
+
+# Cost Tools: Quick Start
+
+## Overview
+
+`token_estimator.py` predicts token consumption and monthly costs using 3-level progressive disclosure analysis.
+
+**Zero deployment cost** - pure estimation. Prevents token bloat before production.
+
+**Theory:** File 05, 10, 15. **This guide:** Usage only.
+
+---
+
+## Installation
+
+```bash
+python3 /mnt/user-data/outputs/scripts/token_estimator.py --help
+```
+
+No dependencies required (uses built-in libraries).
+
+---
+
+## Basic Usage
+
+```bash
+python3 token_estimator.py <skill_path> [--volume N] [--model MODEL] [--format FORMAT]
+```
+
+**Example:**
+```bash
+# Human-readable output (default)
+python3 token_estimator.py ./my-skill/
+
+# JSON output for automation (v1.0.1+)
+python3 token_estimator.py ./my-skill/ --format json
+
+# Output shows:
+# - Progressive disclosure (3 levels)
+# - Usage scenarios (idle/typical/worst)
+# - Cost projections
+# - Optimization recommendations
+```
+
+---
+
+## Options
+
+**Volume:** `--volume N` (default: 1000)
+```bash
+python3 token_estimator.py ./my-skill/ --volume 10000
+# Projects costs for 10K monthly uses
+```
+
+**Model:** `--model MODEL` (default: claude-sonnet-4.5)
+```bash
+python3 token_estimator.py ./my-skill/ --model claude-opus-4
+# Uses Opus pricing ($15/$75 per M tokens)
+```
+
+**Format:** `--format {text|json}` (default: text) *[New in v1.0.1]*
+```bash
+# JSON output - parseable by automation tools
+python3 token_estimator.py ./my-skill/ --format json | python -m json.tool
+
+# Text output - human-readable
+python3 token_estimator.py ./my-skill/ --format text
+```
+
+---
+
+## Workflows
+
+**Baseline Measurement:** `python3 token_estimator.py ./my-skill/` (note typical tokens)
+
+**Post-Optimization:** Re-run after applying File 10, 15 techniques (compare reduction)
+
+**Budget Planning:** `--volume 50000 --model claude-sonnet-4.5` (enterprise projections)
+
+---
+
+## Understanding Output
+
+| Component | Description | Target |
+|-----------|-------------|--------|
+| Level 1 (Metadata) | YAML, always loaded | <100 tokens |
+| Level 2 (Body) | SKILL.md body, when triggered | <5,000 tokens |
+| Level 3 (Refs) | References, on-demand | <2,000 each |
+
+**Scenarios:** Idle (metadata) | Typical (+ body) | With-Ref (+ smallest ref) | Worst (all)
+
+**Cost:** (Input × $3/M) + (Output × $15/M) × Volume | Reference: Files 05, 10
+
+---
+
+## Optimization Loop
+
+1. Baseline: `token_estimator.py ./my-skill/` (e.g., 4,800 typical)
+2. Optimize: Apply File 10, 15 (move to references/, shorten description)
+3. Re-measure: Run again (target: <3,000 typical)
+4. Calculate: Compare costs (e.g., 50% reduction = $230/year savings)
+
+---
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Path not found | `ls ./my-skill/SKILL.md` |
+| High tokens | File 10 (progressive disclosure) |
+| Large metadata | Shorten description |
+
+---
+
+## Best Practices
+
+- ✅ Estimate before building (set token budget)
+- ✅ Check frequently during development
+- ✅ Target: Metadata <100, Body <5,000, Refs <2,000
+- ✅ Final check pre-deployment
+
+**Toolchain:** validate_skill.py → token_estimator.py → optimize → re-check
+
+---
+
+## Quick Reference
+
+```bash
+# Basic estimate (human-readable)
+python3 token_estimator.py ./my-skill/
+
+# JSON output for automation
+python3 token_estimator.py ./my-skill/ --format json
+
+# Custom volume
+python3 token_estimator.py ./my-skill/ --volume 5000
+
+# Opus pricing with JSON output
+python3 token_estimator.py ./my-skill/ --model claude-opus-4 --format json
+```
+
+**Targets:** Metadata <100 | Body <5,000 | Refs <2,000 each
+
+**Next:** Optimize with File 10, 15 techniques if over targets.
+
+**v1.0.1 Changes:** Added `--format` parameter for JSON/text output standardization.

package/skills/skills/skillkit/knowledge/tools/16-security-tools-guide.md

@@ -0,0 +1,122 @@
+---
+title: "Security Tools: Vulnerability Scanning Guide"
+purpose: "Quick start for security_scanner.py automation"
+token_estimate: "800"
+read_priority: "critical"
+read_when: ["Before deployment", "Security audit", "Third-party skill review"]
+related_files:
+  concepts: ["07-security-concerns", "14-validation-theory"]
+  tools: ["security_scanner.py", "validate_skill.py"]
+last_updated: "2025-11-05"
+---
+
+# Security Tools: Quick Start
+
+## Overview
+
+`security_scanner.py` detects 7 types of security vulnerabilities automatically. **Zero false sense of security** - finds real risks.
+
+**Critical for:** Pre-deployment, third-party skill audits, compliance checks.
+
+**Theory:** File 07. **This guide:** Usage only.
+
+---
+
+## Installation
+
+```bash
+python3 /mnt/user-data/outputs/scripts/security_scanner.py --help
+```
+
+No dependencies (uses built-in libraries).
+
+---
+
+## Basic Usage
+
+```bash
+python3 security_scanner.py <skill_path> [--severity LEVEL] [--format FORMAT]
+```
+
+**Example:**
+```bash
+python3 security_scanner.py ./my-skill/
+
+# Output shows:
+# - Critical issues (must fix)
+# - High severity (should fix)
+# - Medium issues (review)
+# - Exit code: 0=ok, 1=high, 2=critical
+```
+
+---
+
+## Vulnerability Types
+
+7 types detected automatically:
+- **CRITICAL:** Hardcoded secrets, shell=True, eval/exec
+- **HIGH:** SQL injection, pickle, unsafe yaml.load()
+- **MEDIUM:** Path traversal, network calls, prompt injection
+
+Reference: File 07 for prevention.
+
+---
+
+## Options
+
+`--severity LEVEL`: Filter by CRITICAL/HIGH/MEDIUM/LOW
+
+`--format json`: Machine-readable for CI/CD
+
+---
+
+## Workflows
+
+**Pre-Deploy:** `security_scanner.py ./skill/` (exit 0=ok, 1=high, 2=critical)
+
+**CI/CD:** `--severity CRITICAL --format json` in pipeline
+
+**Third-Party:** Scan untrusted skills before use
+
+---
+
+## Remediation Guide
+
+| Severity | Action | Common Fixes |
+|----------|--------|--------------|
+| CRITICAL | Do NOT deploy | Env vars for secrets, remove shell=True/eval/exec |
+| HIGH | Fix before prod | Parameterized queries, json instead of pickle |
+| MEDIUM | Review & mitigate | Validate paths, verify network calls (File 07) |
+
+**False Positives:** URLs in docs (expected), review all in context
+
+---
+
+## Best Practices
+
+- ✅ Scan before EVERY deployment (MUST pass)
+- ✅ Address all CRITICAL findings
+- ✅ Never commit secrets (use env vars)
+- ✅ Scan third-party skills before use
+- ✅ Test in isolated environment
+
+**Toolchain:** validate_skill.py → security_scanner.py → token_estimator.py
+
+---
+
+## Quick Reference
+
+```bash
+# Standard scan
+python3 security_scanner.py ./my-skill/
+
+# Critical only
+python3 security_scanner.py ./my-skill/ --severity CRITICAL
+
+# JSON for CI/CD
+python3 security_scanner.py ./my-skill/ --format json
+```
+
+**Exit Codes:** 0=safe | 1=high severity | 2=critical issues
+
+**Next:** File 07 for remediation techniques, validate_skill.py for structure.

package/skills/skills/skillkit/knowledge/tools/17-pattern-tools-guide.md

@@ -0,0 +1,161 @@
+---
+title: "Pattern Tools: Workflow Selection Guide"
+purpose: "Quick start for pattern_detector.py automation"
+token_estimate: "800"
+read_priority: "medium"
+read_when: ["Designing new skill", "Pattern selection needed", "Architecture planning"]
+related_files:
+  concepts: ["04-hybrid-patterns", "09-case-studies", "Panduan-Komprehensif"]
+  tools: ["pattern_detector.py"]
+last_updated: "2025-11-05"
+---
+
+# Pattern Tools: Quick Start
+
+## Overview
+
+`pattern_detector.py` recommends workflow patterns from 8 proven patterns. **Accelerates design** by matching use cases to best practices.
+
+**Use when:** Starting new skill, unsure which pattern fits, learning proven architectures.
+
+**Theory:** Panduan Komprehensif, Files 04, 09. **This guide:** Usage only.
+
+---
+
+## Installation
+
+```bash
+python3 /mnt/user-data/outputs/scripts/pattern_detector.py --help
+```
+
+No dependencies (built-in libraries only).
+
+---
+
+## Basic Usage
+
+```bash
+python3 pattern_detector.py "your use case description" [--format {text|json}]
+python3 pattern_detector.py --interactive
+python3 pattern_detector.py --list [--format {text|json}]
+```
+
+**Example:**
+```bash
+# Human-readable output (default)
+python3 pattern_detector.py "convert PDF to Word"
+
+# JSON output for automation (v1.0.1+)
+python3 pattern_detector.py "convert PDF to Word" --format json
+
+# Output:
+# - Recommended pattern: Read-Process-Write
+# - Match confidence: 33%
+# - Use cases, examples, references
+# - (JSON mode: includes alternatives and structured data)
+```
+
+---
+
+## Three Modes
+
+**1. Analysis Mode:** Describe use case, get recommendation
+```bash
+# Text output (default)
+python3 pattern_detector.py "scan code for security issues"
+
+# JSON output (v1.0.1+)
+python3 pattern_detector.py "scan code for security issues" --format json
+# â†' Search-Analyze-Report pattern with alternatives in JSON
+```
+
+**2. Interactive Mode:** Guided questionnaire
+```bash
+python3 pattern_detector.py --interactive
+# Answer questions â†' Get recommendation
+# Note: Interactive mode does not support JSON output
+```
+
+**3. List Mode:** See all patterns
+```bash
+# Text output - formatted list
+python3 pattern_detector.py --list
+
+# JSON output - parseable structure (v1.0.1+)
+python3 pattern_detector.py --list --format json
+# Shows all 8 patterns with keywords and examples
+```
+
+---
+
+## The 8 Patterns
+
+| Pattern | Use For |
+|---------|---------|
+| Read-Process-Write | File transformations, cleanup |
+| Search-Analyze-Report | Code analysis, security scans |
+| Script Automation | CI/CD, test automation |
+| Wizard Multi-Step | Project setup, configuration |
+| Template Generation | Reports, emails, documents |
+| Iterative Refinement | Code review, optimization |
+| Context Aggregation | Dashboards, status reports |
+| Validation Pipeline | Data validation, compliance |
+
+Reference: Panduan Komprehensif for details.
+
+---
+
+## Workflows
+
+**Selection:** Describe use case → Review recommendation + alternatives → Study pattern (Panduan)
+
+**Learning:** List patterns → Study Panduan → Try interactive mode
+
+---
+
+## Output Interpretation
+
+**Confidence:** >50% (strong) | 30-50% (good, check alternatives) | <30% (weak, try interactive)
+
+**Alternatives:** Shown when confidence < 50%
+
+---
+
+## Best Practices & Tips
+
+- ✅ Use at design phase (before coding)
+- ✅ Review alternatives if confidence < 50%
+- ✅ Include pattern keywords for better matches
+- ✅ Use interactive mode for guidance
+- ✅ Study Panduan + File 04 (hybrid) + File 09 (examples)
+
+---
+
+## Troubleshooting
+
+**Low confidence (<30%):**
+- Use --interactive mode
+- Add more keywords to description
+- Review --list to see all options
+
+**Wrong pattern recommended:**
+- Check alternatives shown
+- Try interactive mode for guided selection
+- Keywords might be misleading (e.g., "report" → template vs analysis)
+
+---
+
+## Quick Reference
+
+```bash
+# Analysis
+python3 pattern_detector.py "convert PDF"
+
+# Interactive
+python3 pattern_detector.py -i
+
+# List all
+python3 pattern_detector.py -l
+```
+
+**Next:** Panduan Komprehensif for pattern details → File 04 for hybrids → File 09 for examples.