insight-skill-generator

What this skill does

# Insight-to-Skill Generator

## Overview

This skill transforms insights from the `extract-explanatory-insights` hook into production-ready Claude Code skills. It discovers insight files, clusters related insights using smart similarity analysis, and guides you through interactive skill creation.

**Key Capabilities**:
- Automatic discovery and parsing of insight files from `docs/lessons-learned/`
- **Deduplication** to remove duplicate entries from extraction hook bugs
- **Quality filtering** to keep only actionable, skill-worthy insights
- Smart clustering using keyword similarity, category matching, and temporal proximity
- Interactive skill design with customizable patterns (phase-based, mode-based, validation)
- Flexible installation (project-specific or global)

## When to Use This Skill

**Trigger Phrases**:
- "create skill from insights"
- "generate skill from lessons learned"
- "turn my insights into a skill"
- "convert docs/lessons-learned to skill"

**Use PROACTIVELY when**:
- User mentions they have accumulated insights in a project
- You notice `docs/lessons-learned/` directory with multiple insights
- User asks how to reuse knowledge from previous sessions
- User wants to create a skill but has raw insights as source material

**NOT for**:
- Creating skills from scratch (use skill-creator instead)
- Creating sub-agents (use sub-agent-creator instead)
- User has no insights or lessons-learned directory
- User wants to create MCP servers (use mcp-server-creator instead)

## Response Style

**Interactive and Educational**: Guide users through each decision point with clear explanations of trade-offs. Provide insights about why certain patterns work better for different insight types.

## Quick Decision Matrix

| User Request | Action | Reference |
|--------------|--------|-----------|
| "create skill from insights" | Full workflow | Start at Phase 1 |
| "show me insight clusters" | Clustering only | `workflow/phase-2-clustering.md` |
| "design skill structure" | Design phase | `workflow/phase-3-design.md` |
| "install generated skill" | Installation | `workflow/phase-5-installation.md` |

## Workflow Overview

### Phase 1: Insight Discovery and Parsing
Locate, read, **deduplicate**, and **quality-filter** insights from lessons-learned directory.
→ **Details**: `workflow/phase-1-discovery.md`

### Phase 2: Smart Clustering
Group related insights using similarity analysis to identify skill candidates.
→ **Details**: `workflow/phase-2-clustering.md`

### Phase 3: Interactive Skill Design
Design skill structure with user customization (name, pattern, complexity).
→ **Details**: `workflow/phase-3-design.md`

### Phase 4: Skill Generation
Create all skill files following the approved design.
→ **Details**: `workflow/phase-4-generation.md`

### Phase 5: Installation and Testing
Install the skill and provide testing guidance.
→ **Details**: `workflow/phase-5-installation.md`

## Quality Thresholds

**Minimum quality score: 4** (out of 9 possible)

Score calculation:
- Has actionable items (checklists, steps): +3
- Has code examples: +2
- Has numbered steps: +2
- Word count > 200: +1
- Has warnings/notes: +1

**Skip insights that are**:
- Basic explanatory notes without actionable steps
- Simple definitions or concept explanations
- Single-paragraph observations

**Keep insights that have**:
- Actionable workflows (numbered steps, checklists)
- Decision frameworks (trade-offs, when to use X vs Y)
- Code patterns with explanation of WHY
- Troubleshooting guides with solutions

## File Naming Convention

Files MUST follow: `YYYY-MM-DD-descriptive-slug.md`
- ✅ `2025-11-21-jwt-refresh-token-pattern.md`
- ✅ `2025-11-20-vitest-mocking-best-practices.md`
- ❌ `2025-11-21.md` (missing description)

## Important Reminders

- **Deduplicate first**: Extraction hook may create 7-8 duplicates per file - always deduplicate
- **Quality over quantity**: Not every insight should become a skill (minimum score: 4)
- **Descriptive filenames**: Use `YYYY-MM-DD-topic-slug.md` format
- **Avoid skill duplication**: Check existing skills before generating
- **User confirmation**: Always get user approval before writing files to disk
- **Pattern selection matters**: Wrong pattern makes skill confusing. When in doubt, use phase-based
- **Test before sharing**: Always test trigger phrases work as expected

## Limitations

- Requires `docs/lessons-learned/` directory with insight files
- Insight quality determines output quality (garbage in, garbage out)
- Cannot modify existing skills (generates new ones only)
- Clustering algorithm may need threshold tuning for different domains

## Reference Materials

| Resource | Purpose |
|----------|---------|
| `workflow/*.md` | Detailed phase instructions |
| `reference/troubleshooting.md` | Common issues and fixes |
| `data/clustering-config.yaml` | Similarity rules and thresholds |
| `data/skill-templates-map.yaml` | Insight-to-skill pattern mappings |
| `data/quality-checklist.md` | Validation criteria |
| `templates/*.md.j2` | Generation templates |
| `examples/` | Sample outputs |

## Success Criteria

- [ ] Insights discovered and parsed from lessons-learned
- [ ] Clusters formed with user approval
- [ ] Skill design approved (name, pattern, structure)
- [ ] All files generated and validated
- [ ] Skill installed in chosen location
- [ ] Trigger phrases tested and working

---

**Version**: 0.2.0
**Author**: Connor
**Integration**: extract-explanatory-insights hook