@rfxlamia/skillkit 1.0.0 → 1.2.0

package/skills/skills/skillkit/knowledge/tools/18-decision-helper-guide.md

@@ -0,0 +1,243 @@
+---
+title: "Decision Helper Tool: Skills vs Subagents"
+purpose: "Guide for using decision_helper.py to get instant recommendations"
+tool_name: "decision_helper.py"
+tool_type: "agent-layer"
+read_priority: "high"
+read_when:
+  - "User asks 'Should I use Skill or Subagent for X?'"
+  - "Decision guidance needed"
+  - "Token efficiency comparison required"
+  - "Before implementing new capability"
+related_files:
+  - "File 02: Skills vs Subagents comparison"
+  - "File 03: Decision tree logic"
+  - "File 05: Token economics"
+token_estimate: "800"
+last_updated: "2025-02-07"
+---
+
+# Decision Helper Tool: Skills vs Subagents
+
+## PURPOSE
+
+Agent-layer tool untuk instant Skills vs Subagents recommendations menggunakan File 03 decision tree. Called BY Claude via bash_tool, NOT for direct human use.
+
+**Flow:** User asks → Claude calls tool → JSON output → Claude explains
+
+---
+
+## THREE MODES
+
+### Mode 1: Pre-Answered (Preferred)
+
+**When:** Claude has extracted clear answers from conversation.
+
+**CRITICAL: Agent MUST create a temp JSON file first.** The `decision_helper.py` script does NOT accept inline JSON strings - it requires a file path to a JSON file.
+
+**Step-by-step workflow (REQUIRED):**
+
+```bash
+# STEP 1: Create temp directory
+mkdir -p ./tmp/skillkit
+
+# STEP 2: Create JSON file with answers (REQUIRED - cannot be inline)
+cat > ./tmp/skillkit/decision-answers.json <<'EOF'
+{
+  "utility_task": false,
+  "multi_step": true,
+  "reusable": false,
+  "specialized_personality": true,
+  "missing_knowledge": false,
+  "coordination": true,
+  "isolated_context": true,
+  "clutter_chat": true
+}
+EOF
+
+# STEP 3: Call decision helper with FILE PATH (not JSON string)
+cd ~/.claude/skills/skillkit && source venv/bin/activate
+python scripts/decision_helper.py --answers ./tmp/skillkit/decision-answers.json
+```
+
+**Required JSON structure:**
+- 8 keys (exact names): `utility_task`, `multi_step`, `reusable`, `specialized_personality`, `missing_knowledge`, `coordination`, `isolated_context`, `clutter_chat`
+- All values MUST be boolean (`true` or `false`), not strings
+- Missing/extra keys will cause validation error
+
+**Accuracy:** Highest (90-95% confidence).
+
+---
+
+### Mode 2: Keyword Inference (Fallback)
+
+**When:** User query ambiguous, inference needed.
+
+**Call (JSON output - default):**
+```bash
+python decision_helper.py --analyze "code review with validation"
+```
+
+**Call (Text output - for debugging):** *[New in v1.0.1]*
+```bash
+python decision_helper.py --analyze "code review with validation" --format text
+```
+
+**Accuracy:** Lower (confidence reduced 15%).
+
+**Note:** Prefer Mode 1 when possible. JSON is default for agent-layer use.
+
+---
+
+### Mode 3: Show Criteria (Reference)
+
+**When:** User asks "How do you decide?"
+
+**Call (JSON output - default):**
+```bash
+python decision_helper.py --show-criteria
+```
+
+**Call (Text output):** *[New in v1.0.1]*
+```bash
+python decision_helper.py --show-criteria --format text
+```
+
+**Output:** All 8 questions + score interpretation table.
+
+---
+
+## OUTPUT STRUCTURE
+
+**Success:**
+```json
+{
+  "status": "success",
+  "recommendation": "Strong Subagent",
+  "score": -6,
+  "confidence": 0.92,
+  "workflow_mode": "full",
+  "mode_reasoning": "Discipline-enforcing skills require behavioral validation",
+  "reasoning": ["Multi-step process...", "Specialized personality..."],
+  "token_analysis": {
+    "skill_approach_tokens": 500,
+    "subagent_approach_tokens": 7500,
+    "cost_multiplier": 15.0
+  },
+  "pattern_suggestions": ["Implement as Subagent", ...],
+  "references": {"conceptual": "File 02", ...}
+}
+```
+
+**Mode selection logic:**
+- Score `>= 6` (Strong/Moderate Skill) + discipline keywords -> `full` mode
+- Score `<= -3` (Subagent) -> not applicable (use subagent creation)
+- Simple utility, no discipline requirement -> `fast` mode
+
+**Error:**
+```json
+{
+  "status": "error",
+  "error_type": "InvalidInput|FileNotFound|InvalidJSON",
+  "message": "...",
+  "help": "..."
+}
+```
+
+**Exit Codes:** 0 = success, 1 = error.
+
+---
+
+## CLAUDE'S USAGE PATTERN
+
+**Step 1:** User asks → Claude analyzes question
+
+**Step 2:** Claude prepares answers.json with 8 boolean values
+
+**Step 3:** Call tool via bash_tool
+
+**Step 4:** Parse JSON output (`json.loads(result.stdout)`)
+
+**Step 5:** Check `status` field:
+- `"success"` → Use recommendation, explain reasoning to user
+- `"error"` → Handle error (retry or ask clarification)
+
+**Example Explanation:**
+```
+Based on analysis, I recommend **Subagent** (92% confidence).
+
+Reasons:
+• Multi-step process needed
+• Specialized personality beneficial
+• Isolated context prevents clutter
+
+Token cost: ~7,500 tokens (15× multiplier, justified for complexity)
+
+See File 03 for decision tree details.
+```
+
+---
+
+## ERROR HANDLING
+
+| Error Type | Fix |
+|------------|-----|
+| `InvalidInput` | Provide all 8 answers |
+| `FileNotFound` | Check path or use --analyze |
+| `InvalidJSON` | Validate JSON syntax |
+| `InvalidType` | Use boolean values (true/false) |
+
+**Recovery:** If error, Claude asks clarification OR retries with Mode 2.
+
+---
+
+## TROUBLESHOOTING
+
+**❌ Common Mistake: Passing inline JSON string**
+```bash
+# WRONG - These will FAIL
+python decision_helper.py --answers "true,true,false,..."
+python decision_helper.py --answers '{"utility_task": true, ...}'
+```
+**Why it fails:** The `--answers` flag expects a FILE PATH, not JSON content.
+The script reads the file at that path (see lines 669-677 of decision_helper.py).
+
+**✅ Correct: Create JSON file first, then pass the file path**
+```bash
+# STEP 1: Create the JSON file
+cat > ./tmp/skillkit/answers.json <<'EOF'
+{
+  "utility_task": true,
+  "multi_step": false,
+  "reusable": true,
+  "specialized_personality": false,
+  "missing_knowledge": false,
+  "coordination": false,
+  "isolated_context": false,
+  "clutter_chat": false
+}
+EOF
+
+# STEP 2: Pass the FILE PATH to --answers
+python decision_helper.py --answers ./tmp/skillkit/answers.json
+```
+
+**Quick validation:**
+```bash
+# Test if file exists and has valid JSON
+test -f ./tmp/skillkit/answers.json && python3 -m json.tool < ./tmp/skillkit/answers.json
+```
+
+---
+
+## REFERENCES
+
+- **File 02:** Skills vs Subagents comparison
+- **File 03:** 8-question decision tree
+- **File 05:** Token economics
+
+**Tool:** `/mnt/user-data/outputs/decision_helper.py` (607 lines, stdlib only)
+
+---
+
+**Status:** ✅ Production-ready | **Version:** 1.0 | **Integration:** Ready for skillkit

package/skills/skills/skillkit/knowledge/tools/19-test-generator-guide.md

@@ -0,0 +1,275 @@
+---
+name: test-generator-guide
+description: "Usage guide for test_generator.py - Auto-generate comprehensive test scenarios for skills"
+---
+
+# Test Generator Usage Guide
+
+**Script:** test_generator.py  
+**Purpose:** Auto-generate comprehensive test scenarios from skill descriptions  
+**Impact:** Saves 1-2 hours per skill testing  
+**References:** File 12 (testing best practices)
+
+---
+
+## Deprecation Notice (v2)
+
+Legacy structural-only mode (running `test_generator.py` without `--behavioral`) is deprecated in v2.
+
+Use v2 style instead:
+
+```bash
+python3 test_generator.py path/to/skill/ --behavioral --test-format pytest
+```
+
+---
+
+## Quick Start
+
+### Basic Usage
+
+```bash
+# v2 recommended (behavioral + pytest)
+python3 test_generator.py path/to/skill/ --behavioral --test-format pytest
+
+# Comprehensive coverage
+python3 test_generator.py path/to/skill/ --coverage comprehensive --behavioral --test-format pytest
+
+# Unittest format
+python3 test_generator.py path/to/skill/ --test-format unittest
+```
+
+### What Gets Generated
+
+```
+skill-directory/
+└── tests/
+    ├── test_scenarios.md    # Human-readable test scenarios
+    └── test_skill.py        # Test implementation skeleton
+```
+
+---
+
+## Coverage Levels
+
+| Level | Description | Scenarios per Capability |
+|-------|-------------|-------------------------|
+| **basic** | Happy path only | 1 scenario |
+| **standard** | Happy + error cases | 3 scenarios |
+| **comprehensive** | Happy + error + edge cases | 5+ scenarios |
+
+**Recommendation:** Use `standard` for most skills, `comprehensive` for critical skills.
+
+---
+
+## Test Formats
+
+### pytest (Default)
+
+```bash
+python3 test_generator.py my-skill/ --test-format pytest
+```
+
+Generates pytest-compatible test functions:
+```python
+def test_01_capability_description():
+    """Test description."""
+    # TODO: Implement test logic
+    pass
+```
+
+**Run tests:** `pytest my-skill/tests/`
+
+### unittest
+
+```bash
+python3 test_generator.py my-skill/ --test-format unittest
+```
+
+Generates unittest.TestCase class:
+```python
+class TestSkill(unittest.TestCase):
+    def test_01_capability_description(self):
+        """Test description."""
+        pass
+```
+
+**Run tests:** `python -m unittest discover my-skill/tests`
+
+### plain
+
+```bash
+python3 test_generator.py my-skill/ --test-format plain
+```
+
+Generates plain text test plan (no code).
+
+---
+
+## How It Works
+
+### 1. Parse SKILL.md
+
+Extracts testable capabilities from:
+- Frontmatter description
+- "can X" patterns
+- WHEN clauses
+- Bullet points
+
+### 2. Generate Scenarios
+
+For each capability:
+- **P0 (Critical):** Happy path
+- **P1 (High):** Error handling + invalid input
+- **P2 (Medium):** Edge cases (empty, large, etc.)
+
+### 3. Write Files
+
+- **test_scenarios.md:** Human-readable documentation
+- **test_skill.py:** Implementation skeleton with TODOs
+
+---
+
+## Examples
+
+### Example 1: JSON Converter Skill
+
+```bash
+$ python3 test_generator.py json-converter/ --coverage standard --test-format pytest
+
+Generating tests for json-converter/...
+Skill: json-converter
+Capabilities found: 2
+Test scenarios generated: 6
+  - P0 (Critical): 2
+  - P1 (High): 4
+  - P2 (Medium): 0
+
+✅ Test documentation: json-converter/tests/test_scenarios.md
+✅ Pytest implementation: json-converter/tests/test_skill.py
+```
+
+### Example 2: Comprehensive Testing
+
+```bash
+$ python3 test_generator.py api-wrapper/ --coverage comprehensive --behavioral --test-format pytest
+
+Test scenarios generated: 15
+  - P0 (Critical): 3
+  - P1 (High): 6
+  - P2 (Medium): 6
+```
+
+---
+
+## Integration with Workflow
+
+### Step 1: Develop Skill
+
+Create your SKILL.md with clear capability descriptions.
+
+### Step 2: Generate Tests
+
+```bash
+python3 test_generator.py my-skill/ --coverage standard --behavioral --test-format pytest
+```
+
+### Step 3: Review Scenarios
+
+```bash
+cat my-skill/tests/test_scenarios.md
+```
+
+Check if all important capabilities are covered.
+
+### Step 4: Implement Tests
+
+Edit `my-skill/tests/test_skill.py` and replace `pass` with actual test logic.
+
+### Step 5: Run Tests
+
+```bash
+pytest my-skill/tests/
+```
+
+---
+
+## Error Handling
+
+### Missing SKILL.md
+
+```bash
+⌠Error: SKILL.md not found in path/to/skill
+```
+
+**Solution:** Ensure skill directory contains SKILL.md file.
+
+### No Capabilities Found
+
+If frontmatter description is too generic, the script may not extract capabilities. 
+
+**Solution:** Add clear capability statements:
+- Use bullet points
+- Include "can X" patterns
+- Add WHEN clauses
+
+---
+
+## Best Practices
+
+**For Better Test Generation:**
+1. Write clear, specific capability descriptions in frontmatter
+2. Use action verbs (convert, parse, analyze, validate)
+3. Include WHEN clauses in SKILL.md content
+4. List features as bullet points
+
+**After Generation:**
+1. Review test_scenarios.md for completeness
+2. Add custom scenarios if needed
+3. Implement test logic incrementally
+4. Start with P0 tests first
+
+---
+
+## Limitations
+
+**What Script CANNOT Do:**
+- Implement actual test logic (provides skeleton only)
+- Infer complex test data without examples
+- Test runtime behavior automatically
+
+**What You Must Do:**
+- Implement test logic in TODO sections
+- Provide skill-specific test inputs
+- Add assertions for expected outputs
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Tests generated successfully |
+| 1 | Invalid skill path or missing SKILL.md |
+| 2 | Unexpected error during generation |
+
+---
+
+## Success Metrics
+
+**Time Savings:**
+- Manual test creation: 1-2 hours
+- Script execution: <5 seconds
+- **Savings:** 99% time reduction
+
+**Coverage:**
+- Standard: 3 scenarios per capability
+- Comprehensive: 5+ scenarios per capability
+- Identifies edge cases automatically
+
+---
+
+**References:**
+- File 12: Testing & Validation (best practices)
+- script-opportunities-analysis.md: Original requirements
+- phase3b-remaining-scripts-planning.md: Implementation plan

package/skills/skills/skillkit/knowledge/tools/20-split-skill-guide.md

@@ -0,0 +1,149 @@
+---
+name: split-skill-guide
+description: "Usage guide for split_skill.py - Auto-split large SKILL.md for progressive disclosure"
+---
+
+# Split Skill Usage Guide
+
+**Script:** split_skill.py  
+**Purpose:** Auto-split large SKILL.md into main file + references  
+**Impact:** Enforces progressive disclosure (200-350 line target)  
+**References:** Files 05, 10 (token optimization, architecture)
+
+---
+
+## Quick Start
+
+### Preview Split (Recommended First)
+
+```bash
+# See what would be split without making changes
+python split_skill.py path/to/skill/ --preview
+```
+
+### Execute Split
+
+```bash
+# Interactive mode (asks for confirmation)
+python split_skill.py path/to/skill/
+
+# Auto mode (no confirmation)
+python split_skill.py path/to/skill/ --auto
+
+# Custom threshold
+python split_skill.py path/to/skill/ --threshold 400
+```
+
+---
+
+## What Gets Split
+
+### Core Sections (Stay in SKILL.md)
+- Overview
+- Installation / Setup
+- Quick Start
+- Basic Usage
+- Core Workflow
+
+### Reference Sections (Move to references/)
+- Advanced usage
+- Troubleshooting
+- Extended examples
+- API reference
+- Edge cases
+- Sections >100 lines
+
+---
+
+## Example Output
+
+**Before:** 721 lines SKILL.md
+
+**After Split:**
+```
+skill/
+├── SKILL.md (212 lines)          # Core content + links
+├── split_report.md                # Split summary
+└── references/
+    ├── advanced-topic-1.md
+    ├── troubleshooting.md         # 82 lines
+    ├── additional-examples.md     # 314 lines
+    └── ... (16 files total)
+```
+
+**Reduction:** 69.1% (721 → 212 lines in main file)
+
+---
+
+## Classification Logic
+
+**Core Criteria (keywords):**
+- overview, setup, installation, quick start
+- basic usage, core, workflow, getting started
+
+**Reference Criteria (keywords):**
+- advanced, troubleshooting, examples, reference
+- edge case, detailed, appendix, additional
+
+**Heuristic:**
+- Sections >100 lines → move to references
+
+---
+
+## Command Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--threshold N` | Line count trigger | 500 |
+| `--preview` | Show plan without executing | False |
+| `--auto` | Skip confirmation | False |
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success or already optimal |
+| 1 | SKILL.md not found |
+| 2 | Unexpected error |
+
+---
+
+## Best Practices
+
+**Before Splitting:**
+1. Run with `--preview` first
+2. Review which sections move to references
+3. Ensure section titles are clear
+
+**After Splitting:**
+1. Review updated SKILL.md
+2. Check reference files are complete
+3. Test cross-reference links
+4. Read split_report.md
+
+---
+
+## Integration with Workflow
+
+```bash
+# Step 1: Develop skill (grows >500 lines)
+# Step 2: Preview split
+python split_skill.py my-skill/ --preview
+
+# Step 3: Execute if satisfied
+python split_skill.py my-skill/ --auto
+
+# Step 4: Validate result
+cat my-skill/SKILL.md
+ls my-skill/references/
+```
+
+---
+
+## References
+
+- File 05: Token Economics (why progressive disclosure matters)
+- File 10: Architecture (optimal file structure)
+- phase3b-remaining-scripts-planning.md: Implementation plan