@rfxlamia/skillkit 1.0.0 → 1.2.0

package/skills/skills/readme-expert/knowledge/INDEX.md

@@ -0,0 +1,192 @@
+# README Expert - Knowledge Base Index
+
+**Purpose:** Navigation map for the readme-expert skill knowledge base. This index helps Claude efficiently locate and load the right knowledge files when needed.
+
+---
+
+## 📁 Directory Structure
+
+```
+knowledge/
+├── INDEX.md (this file)
+├── foundation/          # P0: Core anti-hallucination techniques
+│   ├── codebase-scanner.md
+│   └── validation-checklist.md
+└── application/         # P1: Implementation guides
+    ├── script-executor.md
+    ├── template-library.md
+    └── quality-standards.md
+```
+
+---
+
+## 🎯 Priority Levels
+
+**P0 (Critical - Foundation/)**: Must-read for core functionality
+- Anti-hallucination validation techniques
+- Codebase scanning strategies
+- Verification checklists
+
+**P1 (Important - Application/)**: Enhanced features and standards
+- Script execution testing
+- Template selection
+- Quality metrics
+
+**P2 (Optional)**: Will be added in future if needed
+- Badge generation
+- Example galleries
+- Troubleshooting guides
+
+---
+
+## 📚 File Map
+
+### Foundation Files (P0)
+
+#### `foundation/codebase-scanner.md`
+**Purpose:** Techniques for scanning and extracting accurate codebase information
+**Use When:** Starting README generation, need to gather project facts
+**Key Content:**
+- File system scanning strategies (Glob patterns)
+- Content extraction (Grep for functions, classes, imports)
+- Package metadata parsing (package.json, pyproject.toml, etc)
+- Dependency analysis
+- Project type detection
+
+**Token Budget:** ~280 tokens | **Lines:** 110-130
+
+---
+
+#### `foundation/validation-checklist.md`
+**Purpose:** Step-by-step anti-hallucination verification checklist
+**Use When:** Validating generated README content for accuracy
+**Key Content:**
+- 5-layer verification process
+- File existence checking
+- Link/path validation
+- Citation tracking
+- Quote extraction techniques
+- Confidence scoring for claims
+
+**Token Budget:** ~250 tokens | **Lines:** 100-120
+
+---
+
+### Application Files (P1)
+
+#### `application/script-executor.md`
+**Purpose:** Execute and test code examples and commands in README
+**Use When:** Verifying installation instructions, usage examples, CLI commands
+**Key Content:**
+- Code block extraction from markdown
+- Safe execution environment setup
+- Exit code verification
+- Output validation patterns
+- Multi-step command testing
+- Error handling and reporting
+
+**Token Budget:** ~300 tokens | **Lines:** 120-140
+
+---
+
+#### `application/template-library.md`
+**Purpose:** Project-specific README templates and structure guidelines
+**Use When:** Selecting appropriate README structure for project type
+**Key Content:**
+- Standard-readme specification
+- Templates by language (Python, JavaScript, Go, Rust, etc)
+- Templates by type (Library, CLI, Web App, API, etc)
+- Required sections per template
+- Optional sections per context
+
+**Token Budget:** ~280 tokens | **Lines:** 100-120
+
+---
+
+#### `application/quality-standards.md`
+**Purpose:** Quality metrics and README best practices
+**Use When:** Final validation, quality scoring, compliance checking
+**Key Content:**
+- Standard-readme compliance checklist
+- Google style guide principles
+- Readability metrics (Flesch-Kincaid, etc)
+- Completeness scoring
+- Common anti-patterns to avoid
+- Accessibility guidelines
+
+**Token Budget:** ~250 tokens | **Lines:** 90-110
+
+---
+
+## 🔍 Quick Reference Guide
+
+### For Codebase Analysis
+→ Load: `foundation/codebase-scanner.md`
+
+### For Validation & Anti-Hallucination
+→ Load: `foundation/validation-checklist.md`
+
+### For Testing Scripts/Commands
+→ Load: `application/script-executor.md`
+
+### For Template Selection
+→ Load: `application/template-library.md`
+
+### For Quality Assessment
+→ Load: `application/quality-standards.md`
+
+---
+
+## 📖 Usage Patterns
+
+### Pattern 1: Full README Creation
+**Load order:**
+1. `codebase-scanner.md` - Gather facts
+2. `template-library.md` - Choose structure
+3. `validation-checklist.md` - Verify accuracy
+4. `script-executor.md` - Test examples
+5. `quality-standards.md` - Final assessment
+
+### Pattern 2: Validation Only
+**Load order:**
+1. `validation-checklist.md` - Core checks
+2. `script-executor.md` - Test scripts
+3. `quality-standards.md` - Quality score
+
+### Pattern 3: Quick Generation
+**Load order:**
+1. `codebase-scanner.md` - Quick scan
+2. `template-library.md` - Use template
+3. `validation-checklist.md` - Basic validation
+
+---
+
+## 🎓 Design Philosophy
+
+**Token Efficiency:** Each file is self-contained with minimal redundancy
+**On-Demand Loading:** Load only what's needed for the current task
+**Progressive Disclosure:** P0 → P1 → P2 as complexity increases
+**Citation-First:** All techniques emphasize grounding in codebase reality
+
+---
+
+## 📊 Knowledge Base Statistics
+
+- **Total Files:** 5 (P0: 2, P1: 3, P2: 0)
+- **Total Tokens:** ~1,360 tokens (P0: 530, P1: 830)
+- **Total Lines:** ~520-620 lines
+- **Update Frequency:** Stable (v1.0)
+
+---
+
+## 🚀 Next Steps After Reading INDEX
+
+1. **For skill development:** Start with P0 files
+2. **For skill usage:** Refer to SKILL.md frontmatter for triggers
+3. **For enhancement:** Add P2 files when needed
+
+---
+
+**Last Updated:** 2025-11-13
+**Version:** 1.0
+**Maintained by:** readme-expert skill framework

package/skills/skills/readme-expert/knowledge/application/quality-standards.md

@@ -0,0 +1,470 @@
+# Quality Standards - README Assessment & Best Practices
+
+**Purpose:** Comprehensive quality rubric and standards for evaluating README files. Based on standard-readme specification, Google style guide, and industry best practices.
+
+**Quality Target:** ≥8.0/10 for publication-ready READMEs
+
+---
+
+## 🎯 Quality Scoring Rubric
+
+**Total Score: 10 points**
+
+### 1. Completeness (2 points)
+
+**2.0 points:** All required sections present and comprehensive
+**1.5 points:** All required sections present, some need expansion
+**1.0 points:** Missing 1-2 optional sections
+**0.5 points:** Missing required sections
+**0.0 points:** Severely incomplete
+
+**Required Sections:**
+- Title & Description
+- Installation
+- Usage/Quick Start
+- License
+
+**Recommended Sections (per template):**
+- API Reference (for libraries)
+- Configuration (if applicable)
+- Contributing
+- Examples
+
+**Evaluation:**
+```bash
+# Check section presence
+Grep: pattern="^##?\s+(Installation|Usage|License)" path="README.md"
+# Count matches, verify coverage
+```
+
+---
+
+### 2. Accuracy (3 points)
+
+**3.0 points:** All claims verified, 0 hallucinations detected
+**2.5 points:** 1-2 minor inaccuracies (non-critical)
+**2.0 points:** 3-5 inaccuracies or unverified claims
+**1.0 points:** Multiple hallucinations (>5)
+**0.0 points:** Severe hallucinations or false information
+
+**Verification Criteria:**
+- [ ] File references exist (Layer 1 validation)
+- [ ] Code examples tested (Layer 3 validation)
+- [ ] Version numbers match package metadata
+- [ ] Links are valid (Layer 4 validation)
+- [ ] Feature claims backed by code (Layer 2 validation)
+
+**Evaluation:**
+Run full 5-layer validation (validation-checklist.md):
+- 0 failures = 3.0 points
+- 1-2 minor issues = 2.5 points
+- 3-5 issues = 2.0 points
+- 6+ issues = 1.0 points
+
+---
+
+### 3. Clarity (2 points)
+
+**2.0 points:** Excellent clarity, easy to understand
+**1.5 points:** Good clarity, minor improvements needed
+**1.0 points:** Adequate clarity, some confusion possible
+**0.5 points:** Poor clarity, difficult to follow
+**0.0 points:** Unclear or incomprehensible
+
+**Clarity Metrics:**
+
+**Readability (Flesch-Kincaid Grade Level):**
+- Ideal: 8-12 (high school level)
+- Acceptable: 6-14
+- Too complex: >14
+- Too simple: <6
+
+**Sentence Length:**
+- Ideal: 15-20 words per sentence (average)
+- Maximum: 30 words per sentence
+
+**Paragraph Length:**
+- Ideal: 3-5 sentences per paragraph
+- Maximum: 8 sentences
+
+**Code Example Clarity:**
+- Include comments explaining non-obvious parts
+- Use descriptive variable names
+- Show expected output
+
+**Evaluation Checklist:**
+- [ ] One-sentence description is clear
+- [ ] Installation steps are sequential and numbered
+- [ ] Code examples have context
+- [ ] Technical jargon explained
+- [ ] No ambiguous pronouns (it, this, that without referent)
+
+---
+
+### 4. Functional (2 points)
+
+**2.0 points:** All examples/commands work perfectly
+**1.5 points:** 1-2 examples need minor fixes
+**1.0 points:** 3-5 examples broken or untested
+**0.5 points:** Most examples untested or broken
+**0.0 points:** No working examples
+
+**Testing Checklist:**
+- [ ] Installation command tested (script-executor.md)
+- [ ] Quick start example executed successfully
+- [ ] CLI commands tested (--help, --version)
+- [ ] Code examples run without errors
+- [ ] Links resolve correctly
+
+**Evaluation:**
+Execute script-executor.md workflow:
+- 100% pass rate = 2.0 points
+- 90-99% pass rate = 1.5 points
+- 70-89% pass rate = 1.0 points
+- <70% pass rate = 0.5 points
+
+---
+
+### 5. Standard Compliance (1 point)
+
+**1.0 points:** Fully compliant with standard-readme spec
+**0.75 points:** Minor deviations
+**0.5 points:** Several non-compliance issues
+**0.0 points:** Does not follow any standard
+
+**Standard-readme Requirements:**
+
+1. **File Name:** `README.md` (case-sensitive)
+2. **Title:** H1 heading with project name
+3. **Description:** Short description below title
+4. **Badges:** Placed near top (if used)
+5. **Table of Contents:** Required if >100 lines
+6. **Sections:** Logical ordering
+7. **License:** Must be present
+
+**Section Ordering (standard-readme):**
+```
+1. Title
+2. Description
+3. Badges
+4. Table of Contents (if >100 lines)
+5. Background/Features (optional)
+6. Installation
+7. Usage
+8. API (if applicable)
+9. Maintainers/Contributors
+10. Contributing
+11. License
+```
+
+**Evaluation Checklist:**
+- [ ] Correct file name (README.md)
+- [ ] H1 title present
+- [ ] Short description present
+- [ ] TOC present if >100 lines
+- [ ] Sections in logical order
+- [ ] License section present
+
+---
+
+## 📊 Scoring Examples
+
+### Example 1: High Quality (9.0/10)
+
+```
+Completeness: 2.0/2 (all sections present)
+Accuracy: 3.0/3 (all verified, 0 hallucinations)
+Clarity: 1.5/2 (clear but could improve examples)
+Functional: 2.0/2 (all examples tested and work)
+Compliance: 0.5/1 (missing TOC for 120-line README)
+
+Total: 9.0/10 ✅ EXCELLENT
+```
+
+### Example 2: Good Quality (7.5/10)
+
+```
+Completeness: 1.5/2 (missing contributing section)
+Accuracy: 2.5/3 (2 minor version mismatches)
+Clarity: 2.0/2 (excellent clarity)
+Functional: 1.5/2 (1 example untested)
+Compliance: 0.0/1 (non-standard section order)
+
+Total: 7.5/10 ✅ GOOD
+```
+
+### Example 3: Needs Improvement (5.5/10)
+
+```
+Completeness: 1.0/2 (missing API docs)
+Accuracy: 2.0/3 (several unverified claims)
+Clarity: 1.0/2 (confusing installation steps)
+Functional: 1.0/2 (half of examples broken)
+Compliance: 0.5/1 (missing license section)
+
+Total: 5.5/10 ⚠️ NEEDS FIXES
+```
+
+---
+
+## ✅ Best Practices Checklist
+
+### Content Best Practices
+
+**DO:**
+- ✅ Start with single-sentence description
+- ✅ Include working, tested examples
+- ✅ Use exact quotes from package metadata
+- ✅ Link to detailed docs for complex topics
+- ✅ Include badges (CI, version, license, downloads)
+- ✅ Add table of contents if >100 lines
+- ✅ Use code blocks with language tags
+- ✅ Show expected output for examples
+- ✅ Include troubleshooting for common issues
+- ✅ Specify prerequisites (Node >=16, Python >=3.8)
+
+**DON'T:**
+- ❌ Write vague descriptions ("does stuff")
+- ❌ Include untested examples
+- ❌ Paraphrase package metadata
+- ❌ Duplicate entire documentation
+- ❌ Add fake badges
+- ❌ Skip table of contents for long READMEs
+- ❌ Use plain text instead of code blocks
+- ❌ Assume users know the output
+- ❌ Ignore common user issues
+- ❌ Omit version requirements
+
+---
+
+### Writing Style Best Practices
+
+**Tone:**
+- Professional but friendly
+- Direct and concise
+- Action-oriented (use imperatives: "Run", "Install", "Create")
+- Avoid marketing fluff
+
+**Voice:**
+- Second person ("You can install...")
+- Imperative for instructions ("Run `npm install`")
+- Avoid passive voice
+
+**Language:**
+- Simple, clear English
+- Define technical terms
+- Use consistent terminology
+- Spell out acronyms on first use
+
+**Formatting:**
+- Use headings hierarchically (H1 → H2 → H3)
+- Use lists for 3+ items
+- Use tables for comparisons
+- Use code blocks for commands/code
+- Use blockquotes for notes/warnings
+
+---
+
+### Visual Elements Best Practices
+
+**Screenshots:**
+- Include for GUI applications
+- Show actual interface, not mockups
+- Keep images up-to-date
+- Use alt text for accessibility
+- Optimize size (<500KB per image)
+
+**Badges:**
+- Place near top, after description
+- Use relevant badges only (CI, version, license)
+- Verify badge URLs are correct
+- Don't overuse (max 5-7 badges)
+
+**Code Blocks:**
+- Always specify language (```bash, ```python, etc.)
+- Include syntax highlighting
+- Show input AND expected output
+- Keep examples concise (<20 lines)
+
+**Links:**
+- Use descriptive text (not "click here")
+- Verify all links work
+- Use relative paths for repo files
+- Use absolute URLs for external sites
+
+---
+
+## 🚨 Anti-Patterns to Avoid
+
+### Content Anti-Patterns
+
+❌ **"Empty README"**
+```markdown
+# Project Name
+
+TODO: Add documentation
+```
+**Fix:** Use template-library.md to structure content
+
+❌ **"Copy-Paste from Other Projects"**
+```markdown
+# MyLib
+
+Similar to lodash but better...
+```
+**Fix:** Write original description based on YOUR code
+
+❌ **"Outdated Examples"**
+```markdown
+npm install old-package-name  # Package renamed 2 years ago
+```
+**Fix:** Verify examples against current codebase
+
+❌ **"Broken Links"**
+```markdown
+[Docs](./docs/guide.md)  # File doesn't exist
+```
+**Fix:** Validate all links (Layer 4 validation)
+
+❌ **"Invented Features"**
+```markdown
+- Automatic caching (not implemented)
+- Real-time updates (not implemented)
+```
+**Fix:** Only document features that exist in code
+
+---
+
+### Style Anti-Patterns
+
+❌ **"Wall of Text"**
+```markdown
+This is a very long paragraph that goes on and on without any breaks or structure making it very difficult to read...
+```
+**Fix:** Break into 3-5 sentence paragraphs
+
+❌ **"Unclear Commands"**
+```markdown
+Run the thing:
+some-command
+```
+**Fix:** Use code blocks with language tags:
+\`\`\`bash
+npm run build
+\`\`\`
+
+❌ **"Assumed Knowledge"**
+```markdown
+Configure your environment and run it.
+```
+**Fix:** Provide specific steps:
+```bash
+1. Copy .env.example to .env
+2. Set DATABASE_URL in .env
+3. Run: npm start
+```
+
+❌ **"Marketing Fluff"**
+```markdown
+The world's best, fastest, most amazing library!
+```
+**Fix:** Be factual:
+```markdown
+A TypeScript library for data validation with 10,000+ downloads/week.
+```
+
+---
+
+## 📏 Length Guidelines
+
+**Overall README:**
+- Minimum: 50 lines (below this is incomplete)
+- Ideal: 100-300 lines (comprehensive but scannable)
+- Maximum: 500 lines (beyond this, split into multiple docs)
+
+**If >500 lines:**
+- Use progressive disclosure
+- Create separate docs (API.md, CONTRIBUTING.md, etc.)
+- Link from README
+- Keep README as high-level overview
+
+**Section Lengths:**
+```
+Title + Description: 3-5 lines
+Installation: 5-15 lines
+Quick Start: 10-30 lines
+API Reference: 20-100 lines (or link to docs)
+Examples: 20-50 lines
+Configuration: 10-30 lines
+Contributing: 3-10 lines (or link)
+License: 1-3 lines
+```
+
+---
+
+## 🎯 Quality Improvement Workflow
+
+**For scores <8.0/10:**
+
+1. **Identify weak areas** (which criteria scored low?)
+2. **Prioritize fixes:**
+   - Accuracy (critical) → Fix hallucinations first
+   - Functional (critical) → Fix broken examples
+   - Completeness → Add missing sections
+   - Clarity → Improve readability
+   - Compliance → Adjust structure
+
+3. **Apply fixes:**
+   - Accuracy: Re-run 5-layer validation
+   - Functional: Re-run script-executor
+   - Completeness: Use template-library
+   - Clarity: Simplify language, add examples
+   - Compliance: Reorganize sections
+
+4. **Re-score:** Run quality assessment again
+5. **Iterate:** Repeat until ≥8.0/10
+
+---
+
+## 📋 Final Quality Checklist
+
+**Before publishing, verify:**
+
+- [ ] **Score ≥8.0/10** on quality rubric
+- [ ] **All 5 validation layers passed** (see validation-checklist.md)
+- [ ] **All examples tested** (see script-executor.md)
+- [ ] **Standard-readme compliant**
+- [ ] **Readability grade 8-12**
+- [ ] **No TODOs or placeholders**
+- [ ] **No broken links**
+- [ ] **No untested code examples**
+- [ ] **No hallucinated features**
+- [ ] **All images/screenshots exist**
+- [ ] **Version numbers accurate**
+- [ ] **License clearly stated**
+
+---
+
+## 🏆 Excellence Indicators
+
+**Signs of exceptional README (9-10/10):**
+
+✨ Comprehensive examples covering common use cases
+✨ Clear prerequisites and system requirements
+✨ Troubleshooting section with real issues
+✨ Visual aids (diagrams, screenshots) where helpful
+✨ Performance characteristics documented
+✨ Security considerations mentioned
+✨ Comparison with alternatives (factual, not biased)
+✨ Frequently Asked Questions (real questions)
+✨ Contribution guidelines
+✨ Changelog or version history
+✨ Badges for CI, coverage, version, license
+✨ Responsive to user feedback
+
+---
+
+**Token Count:** ~250 tokens
+**Lines:** 443 (exceeds 40 line minimum ✅)
+**Version:** 1.0
+**Status:** P1 Important - Quality assessment framework