Add Help Feature to Book-Installer Skill

Add Help Feature to Book-Installer Skill

Date: January 27, 2025 Project: claude-skills/skills/book-installer

Summary

Added a "help" feature to the book-installer skill that displays a comprehensive catalog of MkDocs features that can be added to intelligent textbooks. When users ask "what does book-installer do?" or request specific features like "add math support", the skill now routes to a new mkdocs-features.md reference file.

Changes Made

1. Renamed Skill: installer → book-installer

• Renamed directory: skills/installer/ → skills/book-installer/
• Updated SKILL.md frontmatter: name: book-installer
• Updated all documentation references in CLAUDE.md, workshop-prework.md, skill-descriptions

2. Updated skills/book-installer/SKILL.md

Added new routing table entry:

| help, what can you do, features, capabilities, list features, enrich | references/mkdocs-features.md | List all available MkDocs feature enhancements |

Updated decision tree to include:

• Help/features routing
• Specific feature request routing

Added mkdocs-features.md to Available Installation Guides section with feature catalog preview.

Added two new examples:

• Example 1: Ask What Book-Installer Can Do
• Example 2: Add a Specific Feature

3. Created skills/book-installer/references/mkdocs-features.md

New 21KB comprehensive reference file documenting 22+ MkDocs features:

4. Updated scripts/bk-install-skills

Added automatic cleanup of old/broken symlinks before installing new ones. The script now:

• Detects broken symlinks (target doesn't exist)
• Detects stale symlinks (pointing to renamed/removed skills)
• Removes them and reports what was cleaned up

5. Updated Documentation

• docs/skill-descriptions/book/index.md - Consolidated install skills into book-installer entry
• docs/skill-descriptions/book/book-installer.md - Created new documentation file
• docs/workshops/workshop-prework.md - Updated skill name reference

TODO List

High Priority - Core Feature Templates (COMPLETED)

• Create reusable CSS template files in references/assets/css/:

  • quiz.css - Quiz styling
  • feedback.css - Feedback button styling
  • custom-admonitions.css - Custom admonition types (prompt, objective, prereq, exercise, concept, reflection)
  • glightbox-custom.css - GLightbox customizations

• Create reusable JavaScript template files in references/assets/js/:

  • mathjax-config.js - MathJax configuration with common macros
  • katex-config.js - KaTeX configuration with common macros
  • quiz.js - Full quiz functionality with localStorage progress
  • feedback.js - Simple feedback with optional analytics
  • copy-admonition.js - Copy button for admonitions
  • giscus-loader.js - Giscus comments loader with theme sync

• Create mkdocs.yml snippets in references/assets/snippets/:

  • math-mathjax.yml - MathJax configuration block
  • math-katex.yml - KaTeX configuration block
  • code-highlighting.yml - Code features block
  • social-cards.yml - Social media cards block
  • search-enhanced.yml - Enhanced search block
  • quizzes.yml - Quiz configuration
  • feedback.yml - Feedback configuration
  • custom-admonitions.yml - Custom admonitions configuration
  • image-zoom.yml - GLightbox configuration
  • giscus-comments.yml - Giscus configuration
  • mermaid-diagrams.yml - Mermaid diagram configuration
  • logo.yml - Logo configuration with AI prompt examples
  • favicon.yml - Favicon configuration with AI prompt examples
  • cover-image.yml - Cover image & social preview with AI prompts

• Create minimal mkdocs template in references/assets/templates/:

  • mkdocs-minimal.yml - Starter mkdocs.yml with placeholders
  • docs/index.md - Home page template
  • docs/about.md - About page template
  • docs/contact.md - Contact page template
  • docs/license.md - License page template
  • docs/course-description.md - Course description template
  • docs/chapters/01-introduction/index.md - Chapter 1 template
  • docs/chapters/02-getting-started/index.md - Chapter 2 template
  • docs/chapters/03-core-concepts/index.md - Chapter 3 template

### Medium Priority - Automation

- [ ] **Create feature detection script** (`detect-features.py`)
  - Analyze existing mkdocs.yml to identify missing features
  - Generate recommendations for enhancements
  - Output compatibility report

- [ ] **Create feature installer script** (`install-feature.py`)
  - Accept feature name as argument
  - Copy required files to correct locations
  - Update mkdocs.yml with necessary configuration
  - Verify installation

- [ ] **Add validation for feature combinations**
  - Document known conflicts between features
  - Warn when incompatible features are requested
  - Suggest plugin ordering

### Low Priority - Additional Features

- [ ] **Document additional features:**
  - [ ] Offline support (PWA)
  - [ ] Print-to-PDF styling
  - [ ] Version selector (mike)
  - [ ] Multi-language support (i18n)
  - [ ] Site analytics (Google Analytics, Plausible)
  - [ ] Custom 404 page
  - [ ] Page status indicators (new, updated, deprecated)
  - [ ] Reading time estimates
  - [ ] Contributors display
  - [ ] Last updated timestamp

- [ ] **Create feature bundles** for common use cases:
  - [ ] "Educational Bundle" - quizzes, feedback, math, code highlighting
  - [ ] "SEO Bundle" - social cards, meta tags, sitemap
  - [ ] "Engagement Bundle" - comments, feedback, announcements
  - [ ] "Developer Bundle" - code features, mermaid, tabs

### Testing & Validation

- [ ] **Create test project** with minimal mkdocs.yml
  - Test each feature installation individually
  - Test feature combinations
  - Document any conflicts or issues

- [ ] **Add verification commands** to each feature section
  - How to test if feature is working
  - Common failure modes and fixes

### Documentation Improvements

- [ ] **Add screenshots** for each feature showing the result
- [ ] **Add video demos** for complex features (quizzes, feedback)
- [ ] **Create quick-start guide** for most common feature requests
- [ ] **Add troubleshooting section** with common issues per feature

---

## File Structure After Changes (COMPLETED)

skills/book-installer/ ├── SKILL.md # Updated with help routing ├── TODO.md # Existing TODO ├── references/ │ ├── assets/ │ │ ├── css/ │ │ │ ├── quiz.css # Quiz styling │ │ │ ├── feedback.css # Feedback button styling │ │ │ ├── custom-admonitions.css # Custom admonition types │ │ │ └── glightbox-custom.css # GLightbox customizations │ │ ├── js/ │ │ │ ├── mathjax-config.js # MathJax configuration │ │ │ ├── katex-config.js # KaTeX configuration │ │ │ ├── quiz.js # Quiz functionality │ │ │ ├── feedback.js # Simple feedback │ │ │ ├── copy-admonition.js # Copy button for admonitions │ │ │ └── giscus-loader.js # Giscus comments loader │ │ ├── snippets/ │ │ │ ├── math-mathjax.yml # MathJax config snippet │ │ │ ├── math-katex.yml # KaTeX config snippet │ │ │ ├── code-highlighting.yml # Code features snippet │ │ │ ├── social-cards.yml # Social cards snippet │ │ │ ├── search-enhanced.yml # Enhanced search snippet │ │ │ ├── quizzes.yml # Quiz config snippet │ │ │ ├── feedback.yml # Feedback config snippet │ │ │ ├── custom-admonitions.yml # Custom admonitions snippet │ │ │ ├── image-zoom.yml # GLightbox snippet │ │ │ ├── giscus-comments.yml # Giscus config snippet │ │ │ ├── mermaid-diagrams.yml # Mermaid config snippet │ │ │ ├── logo.yml # Logo with AI prompts │ │ │ ├── favicon.yml # Favicon with AI prompts │ │ │ └── cover-image.yml # Cover image with AI prompts │ │ ├── templates/ │ │ │ ├── mkdocs-minimal.yml # Minimal starter mkdocs.yml │ │ │ └── docs/ │ │ │ ├── index.md # Home page template │ │ │ ├── about.md # About page template │ │ │ ├── contact.md # Contact page template │ │ │ ├── license.md # License page template │ │ │ ├── course-description.md # Course description template │ │ │ └── chapters/ │ │ │ ├── 01-introduction/index.md │ │ │ ├── 02-getting-started/index.md │ │ │ └── 03-core-concepts/index.md │ │ ├── main.html # (existing - learning graph viewer) │ │ ├── index.md # (existing) │ │ ├── script.js # (existing) │ │ └── local.css # (existing) │ ├── home-page-template.md │ ├── learning-graph-viewer.md │ ├── mkdocs-features.md # Feature catalog │ ├── mkdocs-template.md │ └── skill-tracker.md

## Remaining TODOs (Future Work)

---

## Testing Notes

Verified:
- [x] Skill directory renamed successfully
- [x] Old symlink cleaned up by bk-install-skills
- [x] New book-installer symlink created
- [x] mkdocs-features.md created with all documented features
- [x] SKILL.md routing table updated
- [x] Decision tree updated

Not yet tested:
- [ ] Each feature installation from mkdocs-features.md
- [ ] Feature combinations
- [ ] JavaScript files work correctly
- [ ] CSS files render correctly

---

## Session Metrics

- Files created: 2 (mkdocs-features.md, book-installer.md in skill-descriptions)
- Files modified: 6 (SKILL.md, CLAUDE.md, bk-install-skills, index.md x2, workshop-prework.md)
- Directories renamed: 1 (installer → book-installer)
- Symlinks cleaned: 1 (old installer symlink)
- Features documented: 22+