193 lines
6.0 KiB
Markdown
193 lines
6.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```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`:
|
|
|
|
```yaml
|
|
category_patterns:
|
|
testing:
|
|
preferred_pattern: validation
|
|
skill_name_suffix: "testing-guide"
|
|
```
|
|
|
|
## Examples
|
|
|
|
See [examples/example-clustering-output.md](examples/example-clustering-output.md) for sample cluster analysis.
|
|
|
|
See [examples/example-generated-skill/](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](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
|