gh-cskiro-claudex-meta-tools/skills/insight-skill-generator/README.md

Insight-to-Skill Generator

Transform your accumulated Claude Code explanatory insights into production-ready, reusable skills.

Overview

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

1. Your project has the extract-explanatory-insights hook configured
2. You have insights stored in docs/lessons-learned/ directory
3. 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

1. Discovery: The skill finds 12 insights across 4 categories
2. Clustering: Groups them into 3 skill candidates:
   • "testing-strategy-guide" (5 insights)
   • "hook-debugging-helper" (4 insights)
   • "performance-optimization" (3 insights)
3. Design: You review and customize each skill proposal
4. Generation: Complete skills are created with SKILL.md, README, examples, etc.
5. 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