The Insight-to-Skill Generator analyzes insights collected by the extract-explanatory-insights hook and converts them into well-structured Claude Code skills. It uses smart clustering to group related insights, guides you through interactive skill design, and generates complete skills following Anthropic's standards.

Perfect for:

Reusing knowledge from previous Claude Code sessions
Creating team-wide skills from project-specific learnings
Building a library of domain-specific productivity tools
Codifying best practices discovered through experience

When to Use

Use this skill when you have insights stored in your project's docs/lessons-learned/ directory and want to turn them into reusable skills.

Trigger Phrases:

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

Quick Start

Prerequisites

Your project has the extract-explanatory-insights hook configured
You have insights stored in docs/lessons-learned/ directory
You're using Claude Code with Explanatory output style

Basic Usage

You: "I have a bunch of insights about testing in docs/lessons-learned/. Can you create a skill from them?"

Claude: [Activates insight-skill-generator]
- Scans your docs/lessons-learned/ directory
- Clusters related testing insights
- Proposes a "testing-best-practices" skill
- Guides you through customization
- Generates and installs the skill

Example Workflow

Discovery: The skill finds 12 insights across 4 categories
Clustering: Groups them into 3 skill candidates:
- "testing-strategy-guide" (5 insights)
- "hook-debugging-helper" (4 insights)
- "performance-optimization" (3 insights)
Design: You review and customize each skill proposal
Generation: Complete skills are created with SKILL.md, README, examples, etc.
Installation: You choose to install "testing-strategy-guide" globally, others project-specific

Installation

Standard Installation

# Clone or copy this skill to your Claude Code skills directory
cp -r insight-skill-generator ~/.claude/skills/

# The skill is now available in all your Claude Code sessions

Project-Specific Installation

# Copy to project's .claude directory
cp -r insight-skill-generator /path/to/project/.claude/skills/

What Gets Generated

For each skill created, you'll get:

Minimal Skill (1 simple insight):

SKILL.md - Main skill instructions
README.md - User documentation
plugin.json - Marketplace metadata
CHANGELOG.md - Version history

Standard Skill (2-4 insights):

All of the above, plus:
data/insights-reference.md - Original insights for reference
examples/usage-examples.md - How to use the skill

Complex Skill (5+ insights):

All of the above, plus:
examples/code-samples.md - Code examples extracted from insights
templates/checklist.md - Actionable checklist

Features

Smart Clustering

Analyzes keywords, categories, and temporal proximity
Groups related insights automatically
Identifies standalone high-value insights
Suggests optimal skill patterns (phase-based, mode-based, validation)

Interactive Design

Proposes skill names and descriptions
Lets you customize every aspect
Shows pattern trade-offs with examples
Previews structure before generation

Quality Assurance

Validates YAML frontmatter syntax
Checks against Anthropic's skill standards
Ensures proper file structure
Verifies all references are valid

Flexible Installation

Choose project-specific or global installation
Detects naming conflicts
Tests skill loading after installation
Provides testing guidance

Configuration

Tuning Clustering

Edit ~/.claude/skills/insight-skill-generator/data/clustering-config.yaml:

thresholds:
  cluster_minimum: 0.6      # Lower = more aggressive clustering
  standalone_quality: 0.8   # Higher = fewer standalone skills

Category Patterns

Customize skill patterns for your domain in data/skill-templates-map.yaml:

category_patterns:
  testing:
    preferred_pattern: validation
    skill_name_suffix: "testing-guide"

Examples

See examples/example-clustering-output.md for sample cluster analysis.

See examples/example-generated-skill/ for a complete generated skill.

Tips

Filter quality: Not every insight should become a skill. Focus on actionable, reusable knowledge
Start minimal: It's easier to expand a skill later than to simplify a complex one
Test thoroughly: Use all trigger phrases to ensure the skill works as expected
Version control: Commit generated skills to git for team sharing
Iterate: Skills can evolve. Version 0.1.0 is just the start

Troubleshooting

No insights found

Verify docs/lessons-learned/ exists in your project
Check that the extract-explanatory-insights hook is configured
Ensure insight files match the naming pattern: YYYY-MM-DD-*.md

Clustering produces weird results

Adjust thresholds in data/clustering-config.yaml
Manually split or combine clusters in Phase 2
Try increasing similarity threshold for tighter clusters

Generated skill doesn't load

Check YAML frontmatter syntax (no tabs, proper format)
Verify skill name is lowercase kebab-case
Restart Claude Code session
Check file permissions

Learn More

For detailed workflow documentation, see SKILL.md.

License

Created by Connor for use with Claude Code. Part of the Claude Code skills ecosystem.

Contributing

Have ideas for improving insight-to-skill generation? Open an issue or submit suggestions through your project's Claude Code configuration.

Version: 0.1.0 Category: Productivity Integration: extract-explanatory-insights hook