Agent Skills: Insight-to-Skill Generator

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