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

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

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