@rfxlamia/skillkit 1.1.0 → 1.2.0

package/skills/skills/skillkit/knowledge/tools/21-quality-scorer-guide.md

@@ -0,0 +1,226 @@
+---
+name: quality-scorer-guide
+description: "Usage guide for quality_scorer.py - Score skill quality against best practices"
+tool_name: "quality_scorer.py"
+tool_type: "agent-layer"
+read_priority: "high"
+read_when:
+  - "User asks 'How good is my skill?'"
+  - "Quality assessment needed"
+  - "Before deployment"
+  - "Quality tracking required"
+related_files:
+  - "Files 01-13: All best practices"
+  - "File 05: Token economics"
+  - "File 07: Security concerns"
+  - "File 10: Architecture standards"
+token_estimate: "900"
+last_updated: "2025-11-07"
+---
+
+# Quality Scorer Guide
+
+## PURPOSE
+
+Agent-layer tool to score skill quality using 100-point system across 5 categories. Called BY Claude via bash_tool, NOT for direct human use.
+
+**Flow:** User asks → Claude calls tool → JSON output → Claude explains
+
+---
+
+## SCORING SYSTEM (100 Points)
+
+| Category | Points | Criteria |
+|----------|--------|----------|
+| **Structure** | 20 | YAML, organization, progressive disclosure, references |
+| **Content** | 30 | Description (WHAT+WHEN), triggers, writing style, examples |
+| **Efficiency** | 20 | Line count, token estimate, bloat detection |
+| **Security** | 15 | No secrets, safe patterns, input validation |
+| **Style** | 15 | Imperative voice, conciseness, clear headers |
+
+**Grade Scale:**
+- A (90-100%): Excellent - Production ready
+- B (80-89%): Good - Minor improvements
+- C (70-79%): Fair - Several improvements needed
+- D (60-69%): Needs Improvement
+- F (<60%): Poor
+
+---
+
+## USAGE (AGENT-LAYER)
+
+### Standard Call
+
+```bash
+python quality_scorer.py /path/to/skill --format json
+```
+
+**Output:**
+```json
+{
+  "status": "success",
+  "skill_path": "/mnt/skills/public/docx",
+  "skill_name": "docx",
+  "overall": {
+    "score": 86,
+    "max": 100,
+    "percentage": 86.0,
+    "grade": "B (Good)"
+  },
+  "categories": {
+    "structure": {"score": 20, "max": 20, "percentage": 100.0, "issues": []},
+    "content": {"score": 28, "max": 30, "percentage": 93.33, "issues": [...]},
+    "efficiency": {"score": 15, "max": 20, "percentage": 75.0, "issues": [...]},
+    "security": {"score": 15, "max": 15, "percentage": 100.0, "issues": []},
+    "style": {"score": 5, "max": 15, "percentage": 33.33, "issues": [...]}
+  },
+  "recommendations": [
+    "Content: Writing style not agent-optimized",
+    "Efficiency: Content bloat detected",
+    "Style: Not using imperative voice"
+  ]
+}
+```
+
+---
+
+### Error Response
+
+```json
+{
+  "status": "error",
+  "error_type": "FileNotFound",
+  "message": "Skill directory not found: /path/to/skill",
+  "help": "Ensure skill directory exists and contains SKILL.md"
+}
+```
+
+**Error Types:**
+- `FileNotFound`: Invalid path or missing SKILL.md
+- `UnexpectedError`: Script error (permissions, malformed files)
+
+---
+
+## CLAUDE'S USAGE PATTERN
+
+**Step 1:** User asks "How good is my skill?"
+
+**Step 2:** Claude calls tool with JSON format:
+```python
+result = bash_tool("python quality_scorer.py /path/to/skill --format json")
+```
+
+**Step 3:** Parse JSON output:
+```python
+data = json.loads(result.stdout)
+if data['status'] == 'success':
+    # Use score and recommendations
+else:
+    # Handle error
+```
+
+**Step 4:** Explain to user naturally:
+```
+Your skill scores **86/100 (Grade B)** - Good quality with minor improvements needed.
+
+**Strengths:**
+✓ Perfect structure (20/20)
+✓ Excellent security (15/15)
+
+**Areas to Improve:**
+âš  Content: Writing style could be more agent-optimized (28/30)
+âš  Efficiency: Some content bloat detected (15/20)
+âš  Style: Use more imperative voice (5/15)
+
+**Recommendations:**
+1. Use more action verbs (Use, Run, Execute)
+2. Reduce section length (move to references/)
+3. Keep sentences concise (<20 words)
+
+See Files 05, 07, 10 for optimization guidance.
+```
+
+---
+
+## CATEGORY DETAILS
+
+### Structure (20 pts)
+- YAML frontmatter valid (5): Has `name:` and `description:`
+- File organization (5): SKILL.md exists, proper directory
+- Progressive disclosure (5): <500 lines OR uses references/
+- Reference files (5): Lowercase names, no spaces
+
+### Content (30 pts)
+- Description quality (10): Includes WHAT task does + WHEN to use
+- Clear triggers (5): Has "use when", "trigger", "invoke" keywords
+- Writing style (10): Uses code blocks, lists, tables, action verbs
+- Inline examples (5): Examples in context, not separate section
+
+### Efficiency (20 pts)
+- Line count (10): <500 lines full, <800 partial
+- Token estimate (5): <5,000 tokens (estimated: chars ÷ 4)
+- No bloat (5): No sections >150 lines, >70% unique content
+
+### Security (15 pts)
+- No secrets (5): No hardcoded API keys, passwords, tokens
+- Safe patterns (5): No `eval()`, `exec()`, `shell=True`
+- Input validation (5): Has validation keywords/code
+
+### Style (15 pts)
+- Imperative voice (5): >70% sentences start with action verbs
+- Concise (5): Average sentence length <20 words
+- Clear headers (5): >70% headers descriptive (>2 words)
+
+---
+
+## EXIT CODES
+
+| Code | Meaning | Quality |
+|------|---------|---------|
+| 0 | Success, score ≥70% | Acceptable quality |
+| 1 | Success but <70%, OR error | Below threshold or invalid |
+| 2 | Unexpected error | Script failure |
+
+**CI/CD Integration:**
+```yaml
+- run: python quality_scorer.py ./skill --format json
+  # Fails if score <70%
+```
+
+---
+
+## HUMAN-READABLE MODE
+
+**For developers debugging:**
+```bash
+# Text output with breakdown
+python quality_scorer.py /path/to/skill --detailed
+
+# Export report files
+python quality_scorer.py /path/to/skill --export report.json
+python quality_scorer.py /path/to/skill --export report.md
+```
+
+**Note:** Human mode is for development only. Claude always uses `--format json`.
+
+---
+
+## REFERENCES
+
+**Best Practices:**
+- Files 01-13: Comprehensive checklist
+- File 05: Token optimization
+- File 07: Security guidelines
+- File 10: Architecture standards
+
+**Related Tools:**
+- `validate_skill.py`: Technical validation
+- `security_scanner.py`: Detailed security audit
+- `split_skill.py`: Fix efficiency via progressive disclosure
+- `token_estimator.py`: Detailed token analysis
+
+**Script:** `/mnt/project/quality_scorer.py` (831 lines)
+
+---
+
+**Status:** ✅ Production-ready | **Version:** 1.0 | **Integration:** Agent-layer JSON output

package/skills/skills/skillkit/knowledge/tools/22-migration-helper-guide.md

@@ -0,0 +1,356 @@
+---
+name: migration-helper-guide
+description: "Usage guide for migration_helper.py - Convert docs to skill format"
+tool_name: "migration_helper.py"
+tool_type: "agent-layer"
+read_priority: "medium"
+read_when:
+  - "User wants to convert existing docs to skill"
+  - "Has markdown or text documentation"
+  - "Needs rapid skill creation"
+  - "Bulk conversion required"
+related_files:
+  - "File 10: Technical architecture"
+  - "File 05: Token economics"
+  - "Files 01-13: Best practices"
+token_estimate: "800"
+last_updated: "2025-11-08"
+---
+
+# Migration Helper Guide
+
+## PURPOSE
+
+Agent-layer tool to convert existing documentation (MD, TXT) to proper skill format. Automates structure generation, section classification, and frontmatter creation.
+
+**Flow:** User provides doc → Claude calls tool → JSON output → Skill created
+
+---
+
+## SUPPORTED FORMATS
+
+| Format | Extension | Status |
+|--------|-----------|--------|
+| Markdown | .md, .markdown | ✅ Full support |
+| Plain text | .txt | ✅ Full support |
+| PDF | .pdf | ❌ Future |
+| DOCX | .docx | ❌ Future |
+
+---
+
+## USAGE (AGENT-LAYER)
+
+### Standard Conversion
+
+```bash
+python migration_helper.py source.md --format json
+```
+
+**Output:**
+```json
+{
+  "status": "success",
+  "source": "company-guide.md",
+  "format": "markdown",
+  "skill_name": "company-guide",
+  "preview": false,
+  "conversion": {
+    "source_lines": 543,
+    "skill_md_lines": 187,
+    "core_sections": 4,
+    "reference_sections": 8,
+    "reduction_percent": 65.6
+  },
+  "output": {
+    "skill_path": "./company-guide",
+    "skill_md": "./company-guide/SKILL.md",
+    "references": ["advanced-features.md", "troubleshooting.md", ...],
+    "report": "./company-guide/conversion_report.md"
+  }
+}
+```
+
+---
+
+### Preview Mode (Before Converting)
+
+```bash
+python migration_helper.py source.md --preview --format json
+```
+
+**Output:** Same structure with `"preview": true` and no files created.
+
+---
+
+### Custom Options
+
+```bash
+# Custom skill name
+python migration_helper.py doc.md --skill-name my-skill --format json
+
+# Custom output directory
+python migration_helper.py doc.md --output-dir ./skills/ --format json
+
+# Combined
+python migration_helper.py doc.md --skill-name my-skill --output-dir ./skills/ --preview --format json
+```
+
+---
+
+## CLASSIFICATION LOGIC
+
+### Core Sections (→ SKILL.md)
+Keywords: overview, introduction, setup, installation, quick start, getting started, basic, usage, workflow, how to use
+
+**Characteristics:**
+- Essential understanding
+- Getting started content
+- Basic workflows
+- ≤100 lines
+
+### Reference Sections (→ references/)
+Keywords: advanced, troubleshooting, examples, reference, API, edge cases, detailed, appendix, additional, extended
+
+**Characteristics:**
+- Advanced topics
+- Detailed examples
+- Technical specs
+- >100 lines
+
+---
+
+## ERROR RESPONSES
+
+### File Not Found
+```json
+{
+  "status": "error",
+  "error_type": "FileNotFound",
+  "message": "Source not found: missing.md",
+  "help": "Ensure source file exists and path is correct"
+}
+```
+
+### Unsupported Format
+```json
+{
+  "status": "error",
+  "error_type": "UnsupportedFormat",
+  "message": "Unsupported format: .pdf",
+  "help": "Only .md, .markdown, and .txt files are supported"
+}
+```
+
+### Unexpected Error
+```json
+{
+  "status": "error",
+  "error_type": "UnexpectedError",
+  "message": "...",
+  "help": "Check file permissions and content format"
+}
+```
+
+---
+
+## CLAUDE'S USAGE PATTERN
+
+**Step 1:** User requests conversion
+```
+User: "Convert this markdown file to a Claude skill"
+```
+
+**Step 2:** Claude calls tool with preview first
+```python
+# Preview to show user what will happen
+result = bash_tool("python migration_helper.py /path/to/doc.md --preview --format json")
+data = json.loads(result.stdout)
+
+if data['status'] == 'success':
+    # Show preview to user
+    print(f"This will create skill '{data['skill_name']}' with:")
+    print(f"- {data['conversion']['core_sections']} core sections")
+    print(f"- {data['conversion']['reference_sections']} reference files")
+    print(f"- {data['conversion']['reduction_percent']}% size reduction")
+```
+
+**Step 3:** If user approves, execute conversion
+```python
+# Actual conversion (without --preview)
+result = bash_tool("python migration_helper.py /path/to/doc.md --format json")
+data = json.loads(result.stdout)
+
+if data['status'] == 'success':
+    # Inform user of success
+    print(f"✅ Skill created at: {data['output']['skill_path']}")
+    print(f"Next: Review SKILL.md and validate structure")
+```
+
+**Step 4:** Suggest next actions
+```
+Next steps:
+1. Review SKILL.md frontmatter
+2. Validate: python validate_skill.py {skill_path}/
+3. Check quality: python quality_scorer.py {skill_path}/ --format json
+```
+
+---
+
+## GENERATED STRUCTURE
+
+```
+{skill-name}/
+├── SKILL.md                  # Core content + frontmatter
+├── conversion_report.md      # Conversion summary
+└── references/               # Reference materials (if any)
+    ├── advanced-features.md
+    ├── troubleshooting.md
+    ├── examples.md
+    └── ...
+```
+
+**SKILL.md includes:**
+- YAML frontmatter (name, description, source)
+- Core sections
+- Additional Resources section (links to references/)
+
+---
+
+## EXIT CODES
+
+| Code | Meaning | Scenario |
+|------|---------|----------|
+| 0 | Success | Conversion completed |
+| 1 | Invalid input | File not found, unsupported format |
+| 2 | Unexpected error | Permission denied, I/O error |
+
+---
+
+## CONVERSION WORKFLOW
+
+**Typical Agent-Layer Flow:**
+
+1. **Parse source** → Detect format, extract sections
+2. **Classify** → Core vs reference sections
+3. **Generate frontmatter** → Auto-create YAML metadata
+4. **Plan** → Calculate reduction, estimate tokens
+5. **Execute** → Create skill structure, generate files
+6. **Report** → Conversion summary with next steps
+
+---
+
+## HUMAN-READABLE MODE
+
+**For developer debugging:**
+
+```bash
+# Preview in console
+python migration_helper.py doc.md --preview
+
+# Convert with console output
+python migration_helper.py doc.md
+
+# Custom options
+python migration_helper.py doc.md --skill-name my-skill --output-dir ./skills/
+```
+
+**Note:** Claude always uses `--format json` for machine-parseable output.
+
+---
+
+## INTEGRATION EXAMPLE
+
+```python
+# Complete skill creation workflow
+
+# Step 1: Convert docs
+convert_result = bash_tool(
+    "python migration_helper.py company-docs.md --format json"
+)
+convert_data = json.loads(convert_result.stdout)
+
+if convert_data['status'] != 'success':
+    # Handle error
+    return
+
+skill_path = convert_data['output']['skill_path']
+
+# Step 2: Validate structure
+validate_result = bash_tool(
+    f"python validate_skill.py {skill_path} --format json"
+)
+
+# Step 3: Check quality
+quality_result = bash_tool(
+    f"python quality_scorer.py {skill_path} --format json"
+)
+quality_data = json.loads(quality_result.stdout)
+
+# Step 4: Optimize if needed
+if quality_data['overall']['percentage'] < 70:
+    # Suggest improvements or split
+    split_result = bash_tool(
+        f"python split_skill.py {skill_path} --preview"
+    )
+
+# Step 5: Report to user
+print(f"✅ Skill created and validated")
+print(f"Quality: {quality_data['overall']['grade']}")
+```
+
+---
+
+## BEST PRACTICES
+
+**Before Converting:**
+1. Use `--preview` first to see conversion plan
+2. Check that source format is supported
+3. Review section titles for better classification
+
+**After Converting:**
+1. ✅ Review SKILL.md frontmatter (update description)
+2. ✅ Add trigger phrases (WHEN to use)
+3. ✅ Validate: `python validate_skill.py {skill}/`
+4. ✅ Test skill in Claude
+5. ✅ Optimize if needed
+
+**For Bulk Conversion:**
+```bash
+for doc in docs/*.md; do
+  python migration_helper.py "$doc" --output-dir ./skills/ --format json
+done
+```
+
+---
+
+## LIMITATIONS
+
+**Current:**
+- MD and TXT only (no PDF, DOCX yet)
+- Auto-generated descriptions may need manual refinement
+- Section classification is heuristic-based (~85% accuracy)
+
+**Workarounds:**
+- Manually edit SKILL.md after conversion
+- Use `--skill-name` for better naming
+- Review classification in preview mode
+
+---
+
+## REFERENCES
+
+**Best Practices:**
+- File 10: Skill structure standards
+- File 05: Progressive disclosure rationale
+- Files 01-13: Complete skill design guide
+
+**Related Tools:**
+- `validate_skill.py`: Validate converted skill
+- `quality_scorer.py`: Assess conversion quality
+- `split_skill.py`: Further optimize if needed
+
+**Script:** `/mnt/project/migration_helper.py` (~560 lines)
+
+---
+
+**Status:** ✅ Production-ready | **Version:** 1.0 | **Integration:** Agent-layer JSON output