Initial commit
This commit is contained in:
Zhongwei Li
122
skills/insight-skill-generator/CHANGELOG.md
Normal file
122
skills/insight-skill-generator/CHANGELOG.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to the insight-skill-generator skill will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [0.1.0] - 2025-11-16
|
||||
|
||||
### Added
|
||||
|
||||
- **Phase 1: Insight Discovery and Parsing**
|
||||
- Automatic discovery of insights in `docs/lessons-learned/` directory
|
||||
- Parse insight files with session metadata extraction
|
||||
- Build structured inventory with keywords and categorization
|
||||
- Support for multiple insight categories (testing, architecture, hooks-and-events, etc.)
|
||||
|
||||
- **Phase 2: Smart Clustering**
|
||||
- Keyword-based similarity analysis
|
||||
- Multi-factor scoring (category, keywords, temporal proximity, content overlap)
|
||||
- Automatic cluster formation with configurable thresholds
|
||||
- Standalone high-quality insight detection
|
||||
- Sub-clustering for large insight groups
|
||||
- Interactive cluster review and customization
|
||||
|
||||
- **Phase 3: Interactive Skill Design**
|
||||
- Intelligent skill naming from insight keywords
|
||||
- Auto-generated descriptions with trigger phrases
|
||||
- Complexity assessment (minimal/standard/complex)
|
||||
- Pattern selection (phase-based/mode-based/validation/data-processing)
|
||||
- Content-to-structure mapping
|
||||
- Workflow/phase definition
|
||||
- Preview and customization before generation
|
||||
|
||||
- **Phase 4: Skill Generation**
|
||||
- Complete SKILL.md generation with proper frontmatter
|
||||
- README.md with usage examples
|
||||
- plugin.json with marketplace metadata
|
||||
- CHANGELOG.md initialization
|
||||
- data/insights-reference.md with original insights
|
||||
- examples/ directory with code samples
|
||||
- templates/ directory with actionable checklists
|
||||
- Comprehensive validation against Anthropic standards
|
||||
|
||||
- **Phase 5: Installation and Testing**
|
||||
- Flexible installation (project-specific or global)
|
||||
- Conflict detection and resolution
|
||||
- Post-installation validation
|
||||
- Skill loading verification
|
||||
- Testing guidance with trigger phrases
|
||||
- Refinement suggestions
|
||||
|
||||
- **Configuration System**
|
||||
- `data/clustering-config.yaml` - Tunable similarity rules and thresholds
|
||||
- `data/skill-templates-map.yaml` - Insight-to-pattern mappings
|
||||
- `data/quality-checklist.md` - Validation criteria
|
||||
|
||||
- **Template System**
|
||||
- `templates/insight-based-skill.md.j2` - SKILL.md structure reference
|
||||
- `templates/insight-reference.md.j2` - Insights consolidation pattern
|
||||
- `templates/insight-checklist.md.j2` - Actionable checklist pattern
|
||||
|
||||
- **Documentation**
|
||||
- Comprehensive SKILL.md with 5-phase workflow
|
||||
- User-friendly README.md with quick start guide
|
||||
- Troubleshooting section for common issues
|
||||
- Example outputs and generated skills
|
||||
|
||||
### Features
|
||||
|
||||
- **Smart Clustering**: Analyzes insights using keyword similarity, category matching, and temporal proximity
|
||||
- **Hybrid Approach**: Generates standalone skills from single insights or comprehensive skills from clusters
|
||||
- **Interactive Guided**: User reviews and customizes every design decision
|
||||
- **Quality Validation**: Ensures generated skills meet Anthropic standards
|
||||
- **Pattern Recognition**: Automatically selects appropriate skill pattern based on insight content
|
||||
- **Deduplication**: Prevents creating skills that duplicate existing functionality
|
||||
|
||||
### Integration
|
||||
|
||||
- Integrates with `extract-explanatory-insights` hook
|
||||
- Reads from `docs/lessons-learned/` directory structure
|
||||
- Supports all insight categories from the hook (testing, configuration, hooks-and-events, security, performance, architecture, version-control, react, typescript, general)
|
||||
|
||||
### Supported Patterns
|
||||
|
||||
- **Phase-based**: Linear workflows with sequential steps
|
||||
- **Mode-based**: Multiple distinct approaches for same domain
|
||||
- **Validation**: Analysis and checking patterns
|
||||
- **Data-processing**: Transform or analyze data patterns
|
||||
|
||||
### Complexity Levels
|
||||
|
||||
- **Minimal**: Single insight, basic structure (SKILL.md, README, plugin.json, CHANGELOG)
|
||||
- **Standard**: 2-4 insights with reference materials and examples
|
||||
- **Complex**: 5+ insights with comprehensive templates and multiple examples
|
||||
|
||||
### Known Limitations
|
||||
|
||||
- Requires `docs/lessons-learned/` directory structure from extract-explanatory-insights hook
|
||||
- Clustering algorithm is keyword-based (not ML-powered)
|
||||
- Templates use Jinja2 syntax for documentation reference only (not programmatically rendered)
|
||||
- First release - patterns and thresholds may need tuning based on usage
|
||||
|
||||
### Notes
|
||||
|
||||
- Generated from research on extract-explanatory-insights hook
|
||||
- Based on Anthropic's official skill creation patterns
|
||||
- Follows skill-creator's guided creation approach
|
||||
- Initial thresholds (cluster_minimum: 0.6, standalone_quality: 0.8) are starting points and may need adjustment
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements (Planned)
|
||||
|
||||
- Auto-detection of existing skill overlap to prevent duplication
|
||||
- ML-based clustering for better semantic grouping
|
||||
- Skill versioning support (updating existing skills with new insights)
|
||||
- Team collaboration features (merging insights from multiple developers)
|
||||
- Export skills to Claudex marketplace format
|
||||
- Integration with cc-insights skill for enhanced pattern detection
|
||||
- Batch generation mode for processing multiple projects
|
||||
- Custom template support for organization-specific skill patterns
|
||||
192
skills/insight-skill-generator/README.md
Normal file
192
skills/insight-skill-generator/README.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# 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
|
||||
147
skills/insight-skill-generator/SKILL.md
Normal file
147
skills/insight-skill-generator/SKILL.md
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
name: insight-skill-generator
|
||||
version: 0.1.0
|
||||
description: Use PROACTIVELY when working with projects that have docs/lessons-learned/ directories to transform Claude Code explanatory insights into reusable, production-ready skills. Analyzes insight files, clusters related content, and generates interactive skills following Anthropic's standards.
|
||||
---
|
||||
|
||||
# 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
|
||||
205
skills/insight-skill-generator/data/clustering-config.yaml
Normal file
205
skills/insight-skill-generator/data/clustering-config.yaml
Normal file
@@ -0,0 +1,205 @@
|
||||
# Clustering Configuration for Insight-to-Skill Generator
|
||||
# Version: 0.1.0
|
||||
|
||||
# Similarity Scoring Weights
|
||||
similarity_weights:
|
||||
same_category: 0.3 # Base score if insights are in same category
|
||||
shared_keyword: 0.1 # Added per shared keyword
|
||||
temporal_proximity: 0.05 # If insights created within temporal_window
|
||||
title_similarity: 0.15 # If titles share significant words
|
||||
content_overlap: 0.2 # If content has overlapping concepts
|
||||
|
||||
# Clustering Thresholds
|
||||
thresholds:
|
||||
cluster_minimum: 0.6 # Minimum score to group insights together
|
||||
standalone_quality: 0.8 # Score for single insight to become standalone skill
|
||||
split_cluster_size: 5 # If cluster > this size, consider splitting by sub-topics
|
||||
|
||||
# Temporal Settings
|
||||
temporal_window: 7 # Days - insights within this window get proximity bonus
|
||||
|
||||
# Category Keywords (from extract-explanatory-insights hook)
|
||||
# Used for semantic grouping beyond directory structure
|
||||
categories:
|
||||
testing:
|
||||
keywords:
|
||||
- test
|
||||
- testing
|
||||
- coverage
|
||||
- tdd
|
||||
- unit
|
||||
- integration
|
||||
- e2e
|
||||
- vitest
|
||||
- jest
|
||||
- assertion
|
||||
- mock
|
||||
- fixture
|
||||
skill_category: tooling
|
||||
|
||||
configuration:
|
||||
keywords:
|
||||
- config
|
||||
- configuration
|
||||
- settings
|
||||
- inheritance
|
||||
- yaml
|
||||
- json
|
||||
- env
|
||||
- environment
|
||||
skill_category: tooling
|
||||
|
||||
hooks-and-events:
|
||||
keywords:
|
||||
- hook
|
||||
- lifecycle
|
||||
- event
|
||||
- trigger
|
||||
- callback
|
||||
- listener
|
||||
- middleware
|
||||
skill_category: productivity
|
||||
|
||||
security:
|
||||
keywords:
|
||||
- security
|
||||
- vulnerability
|
||||
- auth
|
||||
- authentication
|
||||
- authorization
|
||||
- encryption
|
||||
- sanitize
|
||||
- injection
|
||||
- xss
|
||||
- csrf
|
||||
skill_category: analysis
|
||||
|
||||
performance:
|
||||
keywords:
|
||||
- performance
|
||||
- optimize
|
||||
- optimization
|
||||
- cache
|
||||
- caching
|
||||
- lazy
|
||||
- memoize
|
||||
- bundle
|
||||
- latency
|
||||
- throughput
|
||||
skill_category: productivity
|
||||
|
||||
architecture:
|
||||
keywords:
|
||||
- architecture
|
||||
- design
|
||||
- pattern
|
||||
- structure
|
||||
- module
|
||||
- component
|
||||
- layer
|
||||
- separation
|
||||
- coupling
|
||||
- cohesion
|
||||
skill_category: analysis
|
||||
|
||||
version-control:
|
||||
keywords:
|
||||
- git
|
||||
- commit
|
||||
- branch
|
||||
- merge
|
||||
- rebase
|
||||
- pull request
|
||||
- pr
|
||||
- cherry-pick
|
||||
skill_category: devops
|
||||
|
||||
react:
|
||||
keywords:
|
||||
- react
|
||||
- component
|
||||
- tsx
|
||||
- jsx
|
||||
- hooks
|
||||
- useEffect
|
||||
- useState
|
||||
- props
|
||||
- state
|
||||
- render
|
||||
skill_category: tooling
|
||||
|
||||
typescript:
|
||||
keywords:
|
||||
- typescript
|
||||
- type
|
||||
- interface
|
||||
- generic
|
||||
- enum
|
||||
- type guard
|
||||
- union
|
||||
- intersection
|
||||
skill_category: tooling
|
||||
|
||||
general:
|
||||
keywords:
|
||||
- general
|
||||
- best practice
|
||||
- lesson
|
||||
- debugging
|
||||
- troubleshooting
|
||||
skill_category: productivity
|
||||
|
||||
# Complexity Assessment Rules
|
||||
# Determines whether insight(s) become minimal/standard/complex skill
|
||||
complexity_rules:
|
||||
minimal:
|
||||
max_insights: 1
|
||||
max_paragraphs: 3
|
||||
has_code_examples: false
|
||||
description: "Single focused insight, phase-based workflow"
|
||||
|
||||
standard:
|
||||
max_insights: 4
|
||||
min_paragraphs: 3
|
||||
requires_data_dir: true
|
||||
description: "Multiple related insights, comprehensive workflow with reference materials"
|
||||
|
||||
complex:
|
||||
min_insights: 5
|
||||
requires_modes: true
|
||||
requires_examples: true
|
||||
description: "Large insight cluster, mode-based with extensive examples and templates"
|
||||
|
||||
# Skill Naming Heuristics
|
||||
naming:
|
||||
max_length: 40 # Max chars for skill name (kebab-case)
|
||||
remove_words: # Common words to remove from auto-generated names
|
||||
- "insight"
|
||||
- "lesson"
|
||||
- "learned"
|
||||
- "the"
|
||||
- "a"
|
||||
- "an"
|
||||
preferred_suffixes: # Preferred endings for skill names
|
||||
- "guide"
|
||||
- "advisor"
|
||||
- "helper"
|
||||
- "automation"
|
||||
- "analyzer"
|
||||
|
||||
# Description Generation
|
||||
description:
|
||||
max_length: 150 # Soft limit for description (actual limit is 1024)
|
||||
required_elements:
|
||||
- action_verb # Must start with verb (e.g., "Use", "Analyzes", "Guides")
|
||||
- trigger_phrase # Must include "PROACTIVELY when" or "Use when"
|
||||
- benefit # Must describe value/outcome
|
||||
action_verbs:
|
||||
- "Use PROACTIVELY when"
|
||||
- "Guides"
|
||||
- "Analyzes"
|
||||
- "Automates"
|
||||
- "Validates"
|
||||
- "Optimizes"
|
||||
- "Generates"
|
||||
- "Monitors"
|
||||
259
skills/insight-skill-generator/data/quality-checklist.md
Normal file
259
skills/insight-skill-generator/data/quality-checklist.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# Quality Validation Checklist
|
||||
|
||||
Generated skills must pass all validation criteria before installation. This checklist ensures compliance with Anthropic's skill standards and Connor's quality requirements.
|
||||
|
||||
## 1. YAML Frontmatter Validation
|
||||
|
||||
### Required Fields
|
||||
- [ ] `name` field present and valid
|
||||
- Max 64 characters
|
||||
- Lowercase, numbers, hyphens only
|
||||
- No reserved words (skill, claude, anthropic)
|
||||
- Matches directory name
|
||||
|
||||
- [ ] `description` field present and valid
|
||||
- Max 1024 characters
|
||||
- Non-empty
|
||||
- No XML/HTML tags
|
||||
- Action-oriented (starts with verb)
|
||||
|
||||
### Description Quality
|
||||
- [ ] Contains trigger phrase
|
||||
- "Use PROACTIVELY when..." OR
|
||||
- "Use when..." OR
|
||||
- "Guides..." OR
|
||||
- "Analyzes..." OR
|
||||
- Similar action verb
|
||||
|
||||
- [ ] Describes clear value/benefit
|
||||
- What problem does it solve?
|
||||
- What outcome does it produce?
|
||||
|
||||
- [ ] Appropriate for skill category
|
||||
- Aligns with insight category
|
||||
- Matches skill type (tooling/analysis/productivity)
|
||||
|
||||
### Optional Fields (if present)
|
||||
- [ ] `allowed-tools` (Claude Code only)
|
||||
- Valid tool names only
|
||||
- No duplicates
|
||||
|
||||
- [ ] Custom fields are reasonable
|
||||
- `version`, `author`, `category` are common
|
||||
|
||||
## 2. File Structure Validation
|
||||
|
||||
### Required Files
|
||||
- [ ] `SKILL.md` exists and is non-empty
|
||||
- [ ] `README.md` exists and is non-empty
|
||||
- [ ] `plugin.json` exists and is valid JSON
|
||||
- [ ] `CHANGELOG.md` exists with v0.1.0 entry
|
||||
|
||||
### Optional Files (based on complexity)
|
||||
- [ ] `data/` directory if complexity >= standard
|
||||
- [ ] `data/insights-reference.md` if multiple insights
|
||||
- [ ] `examples/` directory if code examples present
|
||||
- [ ] `templates/` directory if actionable checklists exist
|
||||
|
||||
### File Size Limits
|
||||
- [ ] SKILL.md < 500 lines (recommend splitting if larger)
|
||||
- [ ] No single file > 1000 lines
|
||||
- [ ] Total skill size < 1MB
|
||||
|
||||
## 3. SKILL.md Content Quality
|
||||
|
||||
### Structure
|
||||
- [ ] Clear heading hierarchy (h1 → h2 → h3)
|
||||
- [ ] No skipped heading levels
|
||||
- [ ] Consistent formatting throughout
|
||||
|
||||
### Required Sections
|
||||
- [ ] Overview/Introduction
|
||||
- What the skill does
|
||||
- When to use it
|
||||
|
||||
- [ ] Workflow or Phases
|
||||
- Clear step-by-step instructions
|
||||
- Numbered or bulleted steps
|
||||
- Logical progression
|
||||
|
||||
- [ ] Examples (if applicable)
|
||||
- Concrete use cases
|
||||
- Expected outputs
|
||||
|
||||
### Content Quality
|
||||
- [ ] Clear, concise language
|
||||
- [ ] No ambiguous pronouns ("it", "this", "that" without context)
|
||||
- [ ] Consistent terminology (no mixing synonyms)
|
||||
- [ ] Action-oriented instructions (imperative mood)
|
||||
|
||||
### Progressive Disclosure
|
||||
- [ ] SKILL.md serves as table of contents
|
||||
- [ ] Detailed content in separate files (data/, examples/)
|
||||
- [ ] References are one level deep (no nested references)
|
||||
|
||||
## 4. Insight Integration Quality
|
||||
|
||||
### Insight Attribution
|
||||
- [ ] Original insights preserved in `data/insights-reference.md`
|
||||
- [ ] Insights properly dated and sourced
|
||||
- [ ] Session metadata included
|
||||
|
||||
### Content Transformation
|
||||
- [ ] Insights converted to actionable workflow steps
|
||||
- [ ] Problem-solution structure maintained
|
||||
- [ ] Code examples extracted to examples/
|
||||
- [ ] Best practices highlighted in Important Reminders
|
||||
|
||||
### Deduplication
|
||||
- [ ] No duplicate content between skill files
|
||||
- [ ] Cross-references used instead of duplication
|
||||
- [ ] Consolidated similar points
|
||||
|
||||
## 5. Pattern Adherence
|
||||
|
||||
### Selected Pattern (phase-based/mode-based/validation)
|
||||
- [ ] Pattern choice justified by insight content
|
||||
- [ ] Pattern correctly implemented
|
||||
- [ ] Section structure matches pattern conventions
|
||||
|
||||
### Workflow Logic
|
||||
- [ ] Phases/modes are sequential or parallel as appropriate
|
||||
- [ ] Each phase has clear purpose
|
||||
- [ ] Prerequisites stated upfront
|
||||
- [ ] Expected outputs defined
|
||||
|
||||
### Error Handling
|
||||
- [ ] Common pitfalls documented
|
||||
- [ ] Troubleshooting guidance included
|
||||
- [ ] Failure recovery steps provided
|
||||
|
||||
## 6. README.md Quality
|
||||
|
||||
### Required Sections
|
||||
- [ ] Brief overview (1-2 sentences)
|
||||
- [ ] When to use (trigger phrases)
|
||||
- [ ] Quick start example
|
||||
- [ ] Installation instructions (if not standard)
|
||||
|
||||
### Clarity
|
||||
- [ ] User-focused (not developer-focused)
|
||||
- [ ] Examples are copy-pasteable
|
||||
- [ ] Screenshots/diagrams if beneficial
|
||||
|
||||
## 7. plugin.json Validation
|
||||
|
||||
### JSON Validity
|
||||
- [ ] Valid JSON syntax
|
||||
- [ ] No trailing commas
|
||||
- [ ] Proper escaping
|
||||
|
||||
### Required Fields
|
||||
- [ ] `name` matches SKILL.md frontmatter
|
||||
- [ ] `version` follows semver (0.1.0 for new skills)
|
||||
- [ ] `description` matches SKILL.md frontmatter
|
||||
- [ ] `type` is "skill"
|
||||
|
||||
### Optional Fields (if present)
|
||||
- [ ] `author` is reasonable string
|
||||
- [ ] `category` is valid (tooling/analysis/productivity/devops)
|
||||
- [ ] `tags` are relevant keywords
|
||||
|
||||
## 8. Code Quality (if skill includes examples)
|
||||
|
||||
### Code Examples
|
||||
- [ ] Syntax highlighting specified (```language)
|
||||
- [ ] Code is complete and runnable
|
||||
- [ ] No placeholder variables (unless clearly marked)
|
||||
- [ ] Comments explain non-obvious logic
|
||||
|
||||
### Best Practices
|
||||
- [ ] Follows language conventions
|
||||
- [ ] No security vulnerabilities
|
||||
- [ ] No hardcoded credentials
|
||||
- [ ] Error handling demonstrated
|
||||
|
||||
## 9. Accessibility & Usability
|
||||
|
||||
### Trigger Phrases
|
||||
- [ ] Multiple trigger phrases provided
|
||||
- [ ] Phrases are natural language
|
||||
- [ ] Covers different ways users might ask
|
||||
- [ ] PROACTIVELY triggers are specific (not too broad)
|
||||
|
||||
### Searchability
|
||||
- [ ] Skill name reflects function
|
||||
- [ ] Description contains relevant keywords
|
||||
- [ ] Tags (if present) aid discovery
|
||||
|
||||
### User Guidance
|
||||
- [ ] Clear next steps after each phase
|
||||
- [ ] Decision points clearly marked
|
||||
- [ ] Optional vs. required steps distinguished
|
||||
|
||||
## 10. Edge Cases & Robustness
|
||||
|
||||
### Input Handling
|
||||
- [ ] Handles missing/malformed input gracefully
|
||||
- [ ] Validates prerequisites before execution
|
||||
- [ ] Provides helpful error messages
|
||||
|
||||
### Project Variability
|
||||
- [ ] Handles different project structures
|
||||
- [ ] Works with monorepos and single packages
|
||||
- [ ] Adapts to different tech stacks
|
||||
|
||||
### Maintenance
|
||||
- [ ] No hardcoded paths (use relative or user-provided)
|
||||
- [ ] No assumptions about environment
|
||||
- [ ] Graceful degradation if optional tools unavailable
|
||||
|
||||
## 11. Insight-Specific Validation
|
||||
|
||||
### Quality Filter
|
||||
- [ ] Only high-quality insights converted
|
||||
- Actionable (not just informational)
|
||||
- Generally applicable (not project-specific)
|
||||
- Valuable (solves real problem)
|
||||
|
||||
### Relevance
|
||||
- [ ] Skill solves problem not covered by existing skills
|
||||
- [ ] No duplication with skill-creator, sub-agent-creator, etc.
|
||||
- [ ] Unique value proposition clear
|
||||
|
||||
### Scope
|
||||
- [ ] Skill is focused (does one thing well)
|
||||
- [ ] Not too broad (overwhelming)
|
||||
- [ ] Not too narrow (trivial)
|
||||
|
||||
## Scoring
|
||||
|
||||
### Critical (must pass all)
|
||||
All items in sections 1-2 (Frontmatter, File Structure)
|
||||
|
||||
### High Priority (must pass 90%+)
|
||||
Sections 3-5 (Content Quality, Insight Integration, Pattern Adherence)
|
||||
|
||||
### Medium Priority (must pass 80%+)
|
||||
Sections 6-9 (README, plugin.json, Code Quality, Usability)
|
||||
|
||||
### Optional (nice to have)
|
||||
Sections 10-11 (Edge Cases, Insight-Specific)
|
||||
|
||||
## Auto-Fix Opportunities
|
||||
|
||||
Some issues can be auto-corrected:
|
||||
- [ ] Trim description to 1024 chars
|
||||
- [ ] Convert skill name to lowercase kebab-case
|
||||
- [ ] Add missing CHANGELOG.md with v0.1.0
|
||||
- [ ] Generate basic README.md from SKILL.md overview
|
||||
- [ ] Validate and pretty-print JSON files
|
||||
|
||||
## Manual Review Required
|
||||
|
||||
Some issues require user decision:
|
||||
- Ambiguous trigger phrases
|
||||
- Pattern selection uncertainty
|
||||
- Multiple valid skill name options
|
||||
- Content organization choices
|
||||
- Category assignment conflicts
|
||||
304
skills/insight-skill-generator/data/skill-templates-map.yaml
Normal file
304
skills/insight-skill-generator/data/skill-templates-map.yaml
Normal file
@@ -0,0 +1,304 @@
|
||||
# Skill Templates Mapping
|
||||
# Maps insight characteristics to appropriate skill patterns and structures
|
||||
# Version: 0.1.0
|
||||
|
||||
# Pattern Definitions
|
||||
# Based on Anthropic's skill creation patterns
|
||||
patterns:
|
||||
phase-based:
|
||||
description: "Linear workflow with sequential phases"
|
||||
best_for:
|
||||
- "Step-by-step processes"
|
||||
- "Problem-diagnosis-solution flows"
|
||||
- "Single-path workflows"
|
||||
structure:
|
||||
- "## Phase 1: [Name]"
|
||||
- "## Phase 2: [Name]"
|
||||
- "## Phase 3: [Name]"
|
||||
example_skills:
|
||||
- "skill-creator"
|
||||
- "mcp-server-creator"
|
||||
|
||||
mode-based:
|
||||
description: "Multiple distinct workflows/approaches"
|
||||
best_for:
|
||||
- "Different use cases for same domain"
|
||||
- "Beginner vs advanced paths"
|
||||
- "Alternative strategies"
|
||||
structure:
|
||||
- "## Mode 1: [Name]"
|
||||
- "## Mode 2: [Name]"
|
||||
- "## Mode Selection Guide"
|
||||
example_skills:
|
||||
- "react-project-scaffolder"
|
||||
|
||||
validation:
|
||||
description: "Analysis and checking pattern"
|
||||
best_for:
|
||||
- "Code review insights"
|
||||
- "Quality assessment insights"
|
||||
- "Security/performance audits"
|
||||
structure:
|
||||
- "## Analysis Phase"
|
||||
- "## Issue Detection"
|
||||
- "## Recommendations"
|
||||
example_skills:
|
||||
- "codebase-auditor"
|
||||
- "bulletproof-react-auditor"
|
||||
|
||||
data-processing:
|
||||
description: "Transform or analyze data"
|
||||
best_for:
|
||||
- "File parsing insights"
|
||||
- "Data transformation insights"
|
||||
- "Report generation insights"
|
||||
structure:
|
||||
- "## Input Processing"
|
||||
- "## Transformation Logic"
|
||||
- "## Output Generation"
|
||||
example_skills:
|
||||
- "cc-insights"
|
||||
|
||||
# Insight-to-Pattern Mapping Rules
|
||||
mapping_rules:
|
||||
- condition:
|
||||
insight_contains:
|
||||
- "step"
|
||||
- "process"
|
||||
- "workflow"
|
||||
- "first"
|
||||
- "then"
|
||||
- "finally"
|
||||
recommended_pattern: phase-based
|
||||
confidence: high
|
||||
|
||||
- condition:
|
||||
insight_contains:
|
||||
- "approach"
|
||||
- "strategy"
|
||||
- "alternative"
|
||||
- "different ways"
|
||||
- "option"
|
||||
recommended_pattern: mode-based
|
||||
confidence: high
|
||||
|
||||
- condition:
|
||||
insight_contains:
|
||||
- "check"
|
||||
- "validate"
|
||||
- "ensure"
|
||||
- "verify"
|
||||
- "audit"
|
||||
- "review"
|
||||
recommended_pattern: validation
|
||||
confidence: medium
|
||||
|
||||
- condition:
|
||||
insight_contains:
|
||||
- "parse"
|
||||
- "transform"
|
||||
- "analyze data"
|
||||
- "process file"
|
||||
- "extract"
|
||||
recommended_pattern: data-processing
|
||||
confidence: medium
|
||||
|
||||
- condition:
|
||||
has_code_examples: true
|
||||
has_step_by_step: true
|
||||
recommended_pattern: phase-based
|
||||
confidence: high
|
||||
|
||||
- condition:
|
||||
cluster_size: 1
|
||||
complexity: low
|
||||
recommended_pattern: phase-based
|
||||
confidence: high
|
||||
|
||||
- condition:
|
||||
cluster_size: "> 4"
|
||||
has_multiple_approaches: true
|
||||
recommended_pattern: mode-based
|
||||
confidence: medium
|
||||
|
||||
# Insight Content → Skill Section Mappings
|
||||
content_mappings:
|
||||
problem_description:
|
||||
triggers:
|
||||
- "The problem"
|
||||
- "Challenge"
|
||||
- "Issue"
|
||||
- "We encountered"
|
||||
maps_to:
|
||||
section: "## Overview"
|
||||
subsection: "Problem Statement"
|
||||
|
||||
solution_explanation:
|
||||
triggers:
|
||||
- "The solution"
|
||||
- "To fix this"
|
||||
- "We resolved"
|
||||
- "The approach"
|
||||
maps_to:
|
||||
section: "## Workflow"
|
||||
subsection: "Implementation Steps"
|
||||
|
||||
code_example:
|
||||
triggers:
|
||||
- "```"
|
||||
- "Example:"
|
||||
- "For instance"
|
||||
maps_to:
|
||||
section: "## Examples"
|
||||
file: "examples/code-samples.md"
|
||||
|
||||
best_practice:
|
||||
triggers:
|
||||
- "Best practice"
|
||||
- "Always"
|
||||
- "Never"
|
||||
- "Recommended"
|
||||
- "Avoid"
|
||||
maps_to:
|
||||
section: "## Important Reminders"
|
||||
file: "data/insights-reference.md"
|
||||
|
||||
checklist_items:
|
||||
triggers:
|
||||
- "- [ ]"
|
||||
- "1."
|
||||
- "2."
|
||||
- "Steps:"
|
||||
maps_to:
|
||||
section: "## Workflow"
|
||||
file: "templates/checklist.md"
|
||||
|
||||
trade_offs:
|
||||
triggers:
|
||||
- "trade-off"
|
||||
- "pros and cons"
|
||||
- "advantage"
|
||||
- "disadvantage"
|
||||
- "however"
|
||||
maps_to:
|
||||
section: "## Decision Guide"
|
||||
subsection: "Considerations"
|
||||
|
||||
warning_caution:
|
||||
triggers:
|
||||
- "Warning"
|
||||
- "Caution"
|
||||
- "Note"
|
||||
- "Important"
|
||||
- "Be careful"
|
||||
maps_to:
|
||||
section: "## Important Reminders"
|
||||
priority: high
|
||||
|
||||
# Skill Complexity Matrix
|
||||
# Determines file structure based on insight characteristics
|
||||
complexity_matrix:
|
||||
minimal:
|
||||
condition:
|
||||
insight_count: 1
|
||||
total_lines: "< 50"
|
||||
has_code: false
|
||||
structure:
|
||||
- "SKILL.md"
|
||||
- "README.md"
|
||||
- "plugin.json"
|
||||
- "CHANGELOG.md"
|
||||
pattern: phase-based
|
||||
|
||||
standard:
|
||||
condition:
|
||||
insight_count: "2-4"
|
||||
total_lines: "50-200"
|
||||
has_code: true
|
||||
structure:
|
||||
- "SKILL.md"
|
||||
- "README.md"
|
||||
- "plugin.json"
|
||||
- "CHANGELOG.md"
|
||||
- "data/insights-reference.md"
|
||||
- "examples/usage-examples.md"
|
||||
pattern: phase-based
|
||||
|
||||
complex:
|
||||
condition:
|
||||
insight_count: "> 4"
|
||||
total_lines: "> 200"
|
||||
has_multiple_topics: true
|
||||
structure:
|
||||
- "SKILL.md"
|
||||
- "README.md"
|
||||
- "plugin.json"
|
||||
- "CHANGELOG.md"
|
||||
- "data/insights-reference.md"
|
||||
- "examples/usage-examples.md"
|
||||
- "examples/code-samples.md"
|
||||
- "templates/checklist.md"
|
||||
- "templates/workflow-template.md"
|
||||
pattern: mode-based
|
||||
|
||||
# Category-Specific Skill Patterns
|
||||
category_patterns:
|
||||
testing:
|
||||
preferred_pattern: validation
|
||||
skill_name_suffix: "testing-guide"
|
||||
description_template: "Use PROACTIVELY when [testing context] to ensure [quality aspect]"
|
||||
typical_sections:
|
||||
- "Test Strategy"
|
||||
- "Common Pitfalls"
|
||||
- "Best Practices"
|
||||
- "Example Tests"
|
||||
|
||||
architecture:
|
||||
preferred_pattern: validation
|
||||
skill_name_suffix: "architecture-advisor"
|
||||
description_template: "Guides [architecture decision] with [architectural principle]"
|
||||
typical_sections:
|
||||
- "Architectural Principles"
|
||||
- "Pattern Selection"
|
||||
- "Trade-offs Analysis"
|
||||
- "Implementation Guidance"
|
||||
|
||||
hooks-and-events:
|
||||
preferred_pattern: phase-based
|
||||
skill_name_suffix: "hook-automation"
|
||||
description_template: "Automates [hook-related task] for [benefit]"
|
||||
typical_sections:
|
||||
- "Hook Configuration"
|
||||
- "Event Handling"
|
||||
- "Debugging Tips"
|
||||
- "Common Patterns"
|
||||
|
||||
performance:
|
||||
preferred_pattern: validation
|
||||
skill_name_suffix: "performance-optimizer"
|
||||
description_template: "Analyzes [performance aspect] and generates [optimization]"
|
||||
typical_sections:
|
||||
- "Performance Analysis"
|
||||
- "Optimization Techniques"
|
||||
- "Measurement Approach"
|
||||
- "Expected Improvements"
|
||||
|
||||
security:
|
||||
preferred_pattern: validation
|
||||
skill_name_suffix: "security-validator"
|
||||
description_template: "Validates [security aspect] against [security standard]"
|
||||
typical_sections:
|
||||
- "Security Checklist"
|
||||
- "Vulnerability Detection"
|
||||
- "Remediation Steps"
|
||||
- "Verification"
|
||||
|
||||
configuration:
|
||||
preferred_pattern: phase-based
|
||||
skill_name_suffix: "config-helper"
|
||||
description_template: "Guides [configuration task] with [configuration approach]"
|
||||
typical_sections:
|
||||
- "Configuration Setup"
|
||||
- "Common Patterns"
|
||||
- "Troubleshooting"
|
||||
- "Validation"
|
||||
348
skills/insight-skill-generator/docs/lessons-learned/README.md
Normal file
348
skills/insight-skill-generator/docs/lessons-learned/README.md
Normal file
@@ -0,0 +1,348 @@
|
||||
# Lessons Learned Index
|
||||
|
||||
This directory contains auto-extracted insights from Claude Code sessions using the Explanatory output style.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
Insights are organized by category with timestamped, descriptive filenames:
|
||||
|
||||
```
|
||||
docs/lessons-learned/
|
||||
├── README.md (this file)
|
||||
├── architecture/
|
||||
│ ├── 2025-11-14-system-design-patterns.md
|
||||
│ └── 2025-11-10-microservices-architecture.md
|
||||
├── configuration/
|
||||
│ └── 2025-11-12-config-inheritance.md
|
||||
├── hooks-and-events/
|
||||
│ ├── 2025-11-14-hook-debugging-strategy.md
|
||||
│ └── 2025-11-13-lifecycle-events.md
|
||||
├── performance/
|
||||
│ └── 2025-11-11-optimization-techniques.md
|
||||
├── react/
|
||||
│ └── 2025-11-14-component-patterns.md
|
||||
├── security/
|
||||
│ └── 2025-11-09-auth-best-practices.md
|
||||
├── testing/
|
||||
│ └── 2025-11-14-tdd-workflow.md
|
||||
├── typescript/
|
||||
│ └── 2025-11-10-type-safety.md
|
||||
├── version-control/
|
||||
│ └── 2025-11-08-git-workflow.md
|
||||
└── general/
|
||||
└── 2025-11-07-general-tips.md
|
||||
```
|
||||
|
||||
## Categories
|
||||
|
||||
### Architecture
|
||||
|
||||
### Architecture
|
||||
|
||||
### Architecture
|
||||
|
||||
### Architecture
|
||||
|
||||
- [`2025-11-16-skill-design-pattern-selection.md`](./architecture/2025-11-16-skill-design-pattern-selection.md) - 7 insights (Updated: 2025-11-16)
|
||||
- [`2025-11-16-skill-design-pattern-selection.md`](./architecture/2025-11-16-skill-design-pattern-selection.md) - 7 insights (Updated: 2025-11-16)
|
||||
### Architecture
|
||||
|
||||
- [`2025-11-16-skill-design-pattern-selection.md`](./architecture/2025-11-16-skill-design-pattern-selection.md) - 7 insights (Updated: 2025-11-16)
|
||||
- [`2025-11-16-skill-design-pattern-selection.md`](./architecture/2025-11-16-skill-design-pattern-selection.md) - 7 insights (Updated: 2025-11-16)
|
||||
|
||||
**Total**: 7 insights across 1 file
|
||||
|
||||
|
||||
**Total**: 7 insights across 1 file
|
||||
|
||||
- [`2025-11-16-skill-design-pattern-selection.md`](./architecture/2025-11-16-skill-design-pattern-selection.md) - 7 insights (Updated: 2025-11-16)
|
||||
|
||||
**Total**: 7 insights across 1 file
|
||||
|
||||
|
||||
**Total**: 7 insights across 1 file
|
||||
|
||||
- [`2025-11-16-skill-design-pattern-selection.md`](./architecture/2025-11-16-skill-design-pattern-selection.md) - 7 insights (Updated: 2025-11-16)
|
||||
|
||||
**Total**: 7 insights across 1 file
|
||||
|
||||
|
||||
**Total**: 7 insights across 1 file
|
||||
|
||||
- [`2025-11-16-skill-design-pattern-selection.md`](./architecture/2025-11-16-skill-design-pattern-selection.md) - 7 insights (Updated: 2025-11-16)
|
||||
### Configuration
|
||||
|
||||
### Configuration
|
||||
|
||||
|
||||
**Total**: 7 insights across 1 file
|
||||
|
||||
### Configuration
|
||||
|
||||
### Configuration
|
||||
|
||||
### Configuration
|
||||
|
||||
### Configuration
|
||||
|
||||
- [`2025-11-16-configuration-driven-design-pattern.md`](./configuration/2025-11-16-configuration-driven-design-pattern.md) - 10 insights (Updated: 2025-11-16)
|
||||
### Configuration
|
||||
|
||||
- [`2025-11-16-configuration-driven-design-pattern.md`](./configuration/2025-11-16-configuration-driven-design-pattern.md) - 10 insights (Updated: 2025-11-16)
|
||||
- [`2025-11-16-configuration-driven-design-pattern.md`](./configuration/2025-11-16-configuration-driven-design-pattern.md) - 10 insights (Updated: 2025-11-16)
|
||||
|
||||
**Total**: 10 insights across 1 file
|
||||
|
||||
- [`2025-11-16-configuration-driven-design-pattern.md`](./configuration/2025-11-16-configuration-driven-design-pattern.md) - 10 insights (Updated: 2025-11-16)
|
||||
|
||||
**Total**: 10 insights across 1 file
|
||||
|
||||
|
||||
**Total**: 10 insights across 1 file
|
||||
|
||||
|
||||
**Total**: 10 insights across 1 file
|
||||
|
||||
- [`2025-11-16-configuration-driven-design-pattern.md`](./configuration/2025-11-16-configuration-driven-design-pattern.md) - 10 insights (Updated: 2025-11-16)
|
||||
- [`2025-11-16-configuration-driven-design-pattern.md`](./configuration/2025-11-16-configuration-driven-design-pattern.md) - 10 insights (Updated: 2025-11-16)
|
||||
- [`2025-11-16-configuration-driven-design-pattern.md`](./configuration/2025-11-16-configuration-driven-design-pattern.md) - 10 insights (Updated: 2025-11-16)
|
||||
|
||||
**Total**: 10 insights across 1 file
|
||||
|
||||
|
||||
**Total**: 10 insights across 1 file
|
||||
|
||||
|
||||
**Total**: 10 insights across 1 file
|
||||
|
||||
### Version-control
|
||||
|
||||
### Version-control
|
||||
|
||||
### Version-control
|
||||
|
||||
### Version-control
|
||||
|
||||
### Version-control
|
||||
|
||||
### Version-control
|
||||
|
||||
### Version-control
|
||||
|
||||
- [`2025-11-16-skill-discovery-and-validation.md`](./version-control/2025-11-16-skill-discovery-and-validation.md) - 8 insights (Updated: 2025-11-16)
|
||||
- [`2025-11-16-skill-discovery-and-validation.md`](./version-control/2025-11-16-skill-discovery-and-validation.md) - 8 insights (Updated: 2025-11-16)
|
||||
- [`2025-11-16-skill-discovery-and-validation.md`](./version-control/2025-11-16-skill-discovery-and-validation.md) - 8 insights (Updated: 2025-11-16)
|
||||
- [`2025-11-16-skill-discovery-and-validation.md`](./version-control/2025-11-16-skill-discovery-and-validation.md) - 8 insights (Updated: 2025-11-16)
|
||||
|
||||
**Total**: 8 insights across 1 file
|
||||
|
||||
|
||||
**Total**: 8 insights across 1 file
|
||||
|
||||
|
||||
**Total**: 8 insights across 1 file
|
||||
|
||||
|
||||
**Total**: 8 insights across 1 file
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
Each category contains an `insights.md` file with chronologically ordered insights. Insights are automatically categorized based on content analysis.
|
||||
|
||||
### Manual Categorization
|
||||
|
||||
If you need to recategorize an insight:
|
||||
1. Cut the insight from the current file
|
||||
2. Paste it into the appropriate category file
|
||||
3. The index will auto-update on the next extraction
|
||||
|
||||
### Searching
|
||||
|
||||
Use grep to search across all insights:
|
||||
```bash
|
||||
grep -r "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
Or use ripgrep for faster searches:
|
||||
```bash
|
||||
rg "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Auto-generated by extract-explanatory-insights.sh hook*
|
||||
|
||||
## Usage
|
||||
|
||||
Each category contains an `insights.md` file with chronologically ordered insights. Insights are automatically categorized based on content analysis.
|
||||
|
||||
### Manual Categorization
|
||||
|
||||
If you need to recategorize an insight:
|
||||
1. Cut the insight from the current file
|
||||
2. Paste it into the appropriate category file
|
||||
3. The index will auto-update on the next extraction
|
||||
|
||||
### Searching
|
||||
|
||||
Use grep to search across all insights:
|
||||
```bash
|
||||
grep -r "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
Or use ripgrep for faster searches:
|
||||
```bash
|
||||
rg "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Auto-generated by extract-explanatory-insights.sh hook*
|
||||
|
||||
## Usage
|
||||
|
||||
Each category contains an `insights.md` file with chronologically ordered insights. Insights are automatically categorized based on content analysis.
|
||||
|
||||
### Manual Categorization
|
||||
|
||||
If you need to recategorize an insight:
|
||||
1. Cut the insight from the current file
|
||||
2. Paste it into the appropriate category file
|
||||
3. The index will auto-update on the next extraction
|
||||
|
||||
### Searching
|
||||
|
||||
Use grep to search across all insights:
|
||||
```bash
|
||||
grep -r "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
Or use ripgrep for faster searches:
|
||||
```bash
|
||||
rg "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Auto-generated by extract-explanatory-insights.sh hook*
|
||||
|
||||
## Usage
|
||||
|
||||
Each category contains an `insights.md` file with chronologically ordered insights. Insights are automatically categorized based on content analysis.
|
||||
|
||||
### Manual Categorization
|
||||
|
||||
If you need to recategorize an insight:
|
||||
1. Cut the insight from the current file
|
||||
2. Paste it into the appropriate category file
|
||||
3. The index will auto-update on the next extraction
|
||||
|
||||
### Searching
|
||||
|
||||
Use grep to search across all insights:
|
||||
```bash
|
||||
grep -r "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
Or use ripgrep for faster searches:
|
||||
```bash
|
||||
rg "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Auto-generated by extract-explanatory-insights.sh hook*
|
||||
- [`2025-11-16-skill-discovery-and-validation.md`](./version-control/2025-11-16-skill-discovery-and-validation.md) - 8 insights (Updated: 2025-11-16)
|
||||
- [`2025-11-16-skill-discovery-and-validation.md`](./version-control/2025-11-16-skill-discovery-and-validation.md) - 8 insights (Updated: 2025-11-16)
|
||||
- [`2025-11-16-skill-discovery-and-validation.md`](./version-control/2025-11-16-skill-discovery-and-validation.md) - 8 insights (Updated: 2025-11-16)
|
||||
|
||||
**Total**: 8 insights across 1 file
|
||||
|
||||
|
||||
**Total**: 8 insights across 1 file
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
Each category contains an `insights.md` file with chronologically ordered insights. Insights are automatically categorized based on content analysis.
|
||||
|
||||
### Manual Categorization
|
||||
|
||||
If you need to recategorize an insight:
|
||||
1. Cut the insight from the current file
|
||||
2. Paste it into the appropriate category file
|
||||
3. The index will auto-update on the next extraction
|
||||
|
||||
### Searching
|
||||
|
||||
Use grep to search across all insights:
|
||||
```bash
|
||||
grep -r "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
Or use ripgrep for faster searches:
|
||||
```bash
|
||||
rg "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Auto-generated by extract-explanatory-insights.sh hook*
|
||||
|
||||
## Usage
|
||||
|
||||
Each category contains an `insights.md` file with chronologically ordered insights. Insights are automatically categorized based on content analysis.
|
||||
|
||||
### Manual Categorization
|
||||
|
||||
If you need to recategorize an insight:
|
||||
1. Cut the insight from the current file
|
||||
2. Paste it into the appropriate category file
|
||||
3. The index will auto-update on the next extraction
|
||||
|
||||
### Searching
|
||||
|
||||
Use grep to search across all insights:
|
||||
```bash
|
||||
grep -r "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
Or use ripgrep for faster searches:
|
||||
```bash
|
||||
rg "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Auto-generated by extract-explanatory-insights.sh hook*
|
||||
|
||||
**Total**: 8 insights across 1 file
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
Each category contains an `insights.md` file with chronologically ordered insights. Insights are automatically categorized based on content analysis.
|
||||
|
||||
### Manual Categorization
|
||||
|
||||
If you need to recategorize an insight:
|
||||
1. Cut the insight from the current file
|
||||
2. Paste it into the appropriate category file
|
||||
3. The index will auto-update on the next extraction
|
||||
|
||||
### Searching
|
||||
|
||||
Use grep to search across all insights:
|
||||
```bash
|
||||
grep -r "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
Or use ripgrep for faster searches:
|
||||
```bash
|
||||
rg "your search term" docs/lessons-learned/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Auto-generated by extract-explanatory-insights.sh hook*
|
||||
@@ -0,0 +1,114 @@
|
||||
# Architecture Insights - November 16, 2025
|
||||
|
||||
Auto-generated lessons learned from Claude Code Explanatory insights.
|
||||
|
||||
**Session**: 79b654b6-10f8-4c3c-92e1-a3535644366c
|
||||
**Generated**: 2025-11-16 09:57:31
|
||||
|
||||
---
|
||||
|
||||
## Skill Design Pattern Selection
|
||||
|
||||
**Skill Design Pattern Selection**
|
||||
|
||||
The research revealed three key patterns for skill creation:
|
||||
1. **Phase-based workflow** (used by skill-creator) - best for linear, multi-step processes
|
||||
2. **Mode-based approach** (used by complex skills) - best for multiple distinct workflows
|
||||
3. **Validation pattern** (used by auditor skills) - best for analysis and checking
|
||||
|
||||
For our insight-to-skill generator, we'll use the **phase-based workflow** pattern because the process is inherently sequential (discover → cluster → design → generate → install), and it aligns with how skill-creator already works, making the user experience consistent.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill Design Pattern Selection
|
||||
|
||||
**Skill Design Pattern Selection**
|
||||
|
||||
The research revealed three key patterns for skill creation:
|
||||
1. **Phase-based workflow** (used by skill-creator) - best for linear, multi-step processes
|
||||
2. **Mode-based approach** (used by complex skills) - best for multiple distinct workflows
|
||||
3. **Validation pattern** (used by auditor skills) - best for analysis and checking
|
||||
|
||||
For our insight-to-skill generator, we'll use the **phase-based workflow** pattern because the process is inherently sequential (discover → cluster → design → generate → install), and it aligns with how skill-creator already works, making the user experience consistent.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill Design Pattern Selection
|
||||
|
||||
**Skill Design Pattern Selection**
|
||||
|
||||
The research revealed three key patterns for skill creation:
|
||||
1. **Phase-based workflow** (used by skill-creator) - best for linear, multi-step processes
|
||||
2. **Mode-based approach** (used by complex skills) - best for multiple distinct workflows
|
||||
3. **Validation pattern** (used by auditor skills) - best for analysis and checking
|
||||
|
||||
For our insight-to-skill generator, we'll use the **phase-based workflow** pattern because the process is inherently sequential (discover → cluster → design → generate → install), and it aligns with how skill-creator already works, making the user experience consistent.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill Design Pattern Selection
|
||||
|
||||
**Skill Design Pattern Selection**
|
||||
|
||||
The research revealed three key patterns for skill creation:
|
||||
1. **Phase-based workflow** (used by skill-creator) - best for linear, multi-step processes
|
||||
2. **Mode-based approach** (used by complex skills) - best for multiple distinct workflows
|
||||
3. **Validation pattern** (used by auditor skills) - best for analysis and checking
|
||||
|
||||
For our insight-to-skill generator, we'll use the **phase-based workflow** pattern because the process is inherently sequential (discover → cluster → design → generate → install), and it aligns with how skill-creator already works, making the user experience consistent.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill Design Pattern Selection
|
||||
|
||||
**Skill Design Pattern Selection**
|
||||
|
||||
The research revealed three key patterns for skill creation:
|
||||
1. **Phase-based workflow** (used by skill-creator) - best for linear, multi-step processes
|
||||
2. **Mode-based approach** (used by complex skills) - best for multiple distinct workflows
|
||||
3. **Validation pattern** (used by auditor skills) - best for analysis and checking
|
||||
|
||||
For our insight-to-skill generator, we'll use the **phase-based workflow** pattern because the process is inherently sequential (discover → cluster → design → generate → install), and it aligns with how skill-creator already works, making the user experience consistent.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill Design Pattern Selection
|
||||
|
||||
**Skill Design Pattern Selection**
|
||||
|
||||
The research revealed three key patterns for skill creation:
|
||||
1. **Phase-based workflow** (used by skill-creator) - best for linear, multi-step processes
|
||||
2. **Mode-based approach** (used by complex skills) - best for multiple distinct workflows
|
||||
3. **Validation pattern** (used by auditor skills) - best for analysis and checking
|
||||
|
||||
For our insight-to-skill generator, we'll use the **phase-based workflow** pattern because the process is inherently sequential (discover → cluster → design → generate → install), and it aligns with how skill-creator already works, making the user experience consistent.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill Design Pattern Selection
|
||||
|
||||
**Skill Design Pattern Selection**
|
||||
|
||||
The research revealed three key patterns for skill creation:
|
||||
1. **Phase-based workflow** (used by skill-creator) - best for linear, multi-step processes
|
||||
2. **Mode-based approach** (used by complex skills) - best for multiple distinct workflows
|
||||
3. **Validation pattern** (used by auditor skills) - best for analysis and checking
|
||||
|
||||
For our insight-to-skill generator, we'll use the **phase-based workflow** pattern because the process is inherently sequential (discover → cluster → design → generate → install), and it aligns with how skill-creator already works, making the user experience consistent.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,169 @@
|
||||
# Configuration Insights - November 16, 2025
|
||||
|
||||
Auto-generated lessons learned from Claude Code Explanatory insights.
|
||||
|
||||
**Session**: 79b654b6-10f8-4c3c-92e1-a3535644366c
|
||||
**Generated**: 2025-11-16 09:57:31
|
||||
|
||||
---
|
||||
|
||||
larity thresholds without editing code
|
||||
2. Add new categories and keywords as their projects evolve
|
||||
3. Customize skill generation patterns for their domain
|
||||
|
||||
This approach follows the "data over code" principle from the skill-creator research, making the skill more maintainable and adaptable.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Configuration-Driven Design Pattern
|
||||
|
||||
**Configuration-Driven Design Pattern**
|
||||
|
||||
Rather than hardcoding clustering logic, we're externalizing it to YAML configuration files. This allows users to:
|
||||
1. Tune similarity thresholds without editing code
|
||||
2. Add new categories and keywords as their projects evolve
|
||||
3. Customize skill generation patterns for their domain
|
||||
|
||||
This approach follows the "data over code" principle from the skill-creator research, making the skill more maintainable and adaptable.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Configuration-Driven Design Pattern
|
||||
|
||||
**Configuration-Driven Design Pattern**
|
||||
|
||||
Rather than hardcoding clustering logic, we're externalizing it to YAML configuration files. This allows users to:
|
||||
1. Tune similarity thresholds without editing code
|
||||
2. Add new categories and keywords as their projects evolve
|
||||
3. Customize skill generation patterns for their domain
|
||||
|
||||
This approach follows the "data over code" principle from the skill-creator research, making the skill more maintainable and adaptable.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Configuration-Driven Design Pattern
|
||||
|
||||
**Configuration-Driven Design Pattern**
|
||||
|
||||
Rather than hardcoding clustering logic, we're externalizing it to YAML configuration files. This allows users to:
|
||||
1. Tune similarity thresholds without editing code
|
||||
2. Add new categories and keywords as their projects evolve
|
||||
3. Customize skill generation patterns for their domain
|
||||
|
||||
This approach follows the "data over code" principle from the skill-creator research, making the skill more maintainable and adaptable.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Template-Based Documentation vs. Executable Logic
|
||||
|
||||
**Template-Based Documentation vs. Executable Logic**
|
||||
|
||||
Notice that our templates use Jinja2-style syntax (`{{ variable }}`), but this is for documentation and reference only. In Claude Code skills, the actual logic is expressed as clear, step-by-step instructions in SKILL.md that I (Claude) interpret and execute. The templates serve as:
|
||||
1. **Consistency guides** - showing expected output structure
|
||||
2. **Reference patterns** - documenting best practices
|
||||
3. **Quality standards** - setting expectations for generated content
|
||||
|
||||
This is different from traditional code generation where templates are programmatically rendered. Here, I read the templates as examples and generate similar output naturally.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Template-Based Documentation vs. Executable Logic
|
||||
|
||||
**Template-Based Documentation vs. Executable Logic**
|
||||
|
||||
Notice that our templates use Jinja2-style syntax (`{{ variable }}`), but this is for documentation and reference only. In Claude Code skills, the actual logic is expressed as clear, step-by-step instructions in SKILL.md that I (Claude) interpret and execute. The templates serve as:
|
||||
1. **Consistency guides** - showing expected output structure
|
||||
2. **Reference patterns** - documenting best practices
|
||||
3. **Quality standards** - setting expectations for generated content
|
||||
|
||||
This is different from traditional code generation where templates are programmatically rendered. Here, I read the templates as examples and generate similar output naturally.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Template-Based Documentation vs. Executable Logic
|
||||
|
||||
**Template-Based Documentation vs. Executable Logic**
|
||||
|
||||
Notice that our templates use Jinja2-style syntax (`{{ variable }}`), but this is for documentation and reference only. In Claude Code skills, the actual logic is expressed as clear, step-by-step instructions in SKILL.md that I (Claude) interpret and execute. The templates serve as:
|
||||
1. **Consistency guides** - showing expected output structure
|
||||
2. **Reference patterns** - documenting best practices
|
||||
3. **Quality standards** - setting expectations for generated content
|
||||
|
||||
This is different from traditional code generation where templates are programmatically rendered. Here, I read the templates as examples and generate similar output naturally.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Template-Based Documentation vs. Executable Logic
|
||||
|
||||
**Template-Based Documentation vs. Executable Logic**
|
||||
|
||||
Notice that our templates use Jinja2-style syntax (`{{ variable }}`), but this is for documentation and reference only. In Claude Code skills, the actual logic is expressed as clear, step-by-step instructions in SKILL.md that I (Claude) interpret and execute. The templates serve as:
|
||||
1. **Consistency guides** - showing expected output structure
|
||||
2. **Reference patterns** - documenting best practices
|
||||
3. **Quality standards** - setting expectations for generated content
|
||||
|
||||
This is different from traditional code generation where templates are programmatically rendered. Here, I read the templates as examples and generate similar output naturally.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Template-Based Documentation vs. Executable Logic
|
||||
|
||||
**Template-Based Documentation vs. Executable Logic**
|
||||
|
||||
Notice that our templates use Jinja2-style syntax (`{{ variable }}`), but this is for documentation and reference only. In Claude Code skills, the actual logic is expressed as clear, step-by-step instructions in SKILL.md that I (Claude) interpret and execute. The templates serve as:
|
||||
1. **Consistency guides** - showing expected output structure
|
||||
2. **Reference patterns** - documenting best practices
|
||||
3. **Quality standards** - setting expectations for generated content
|
||||
|
||||
This is different from traditional code generation where templates are programmatically rendered. Here, I read the templates as examples and generate similar output naturally.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Template-Based Documentation vs. Executable Logic
|
||||
|
||||
**Template-Based Documentation vs. Executable Logic**
|
||||
|
||||
Notice that our templates use Jinja2-style syntax (`{{ variable }}`), but this is for documentation and reference only. In Claude Code skills, the actual logic is expressed as clear, step-by-step instructions in SKILL.md that I (Claude) interpret and execute. The templates serve as:
|
||||
1. **Consistency guides** - showing expected output structure
|
||||
2. **Reference patterns** - documenting best practices
|
||||
3. **Quality standards** - setting expectations for generated content
|
||||
|
||||
This is different from traditional code generation where templates are programmatically rendered. Here, I read the templates as examples and generate similar output naturally.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Template-Based Documentation vs. Executable Logic
|
||||
|
||||
**Template-Based Documentation vs. Executable Logic**
|
||||
|
||||
Notice that our templates use Jinja2-style syntax (`{{ variable }}`), but this is for documentation and reference only. In Claude Code skills, the actual logic is expressed as clear, step-by-step instructions in SKILL.md that I (Claude) interpret and execute. The templates serve as:
|
||||
1. **Consistency guides** - showing expected output structure
|
||||
2. **Reference patterns** - documenting best practices
|
||||
3. **Quality standards** - setting expectations for generated content
|
||||
|
||||
This is different from traditional code generation where templates are programmatically rendered. Here, I read the templates as examples and generate similar output naturally.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,154 @@
|
||||
# Version-control Insights - November 16, 2025
|
||||
|
||||
Auto-generated lessons learned from Claude Code Explanatory insights.
|
||||
|
||||
**Session**: 79b654b6-10f8-4c3c-92e1-a3535644366c
|
||||
**Generated**: 2025-11-16 09:57:31
|
||||
|
||||
---
|
||||
|
||||
valid YAML between `---` delimiters
|
||||
2. **Required fields** - `name` and `description` must be present and valid
|
||||
3. **Name format** - Lowercase kebab-case, max 64 chars
|
||||
4. **Description format** - Max 1024 chars, contains action verbs
|
||||
|
||||
By validating these before even attempting to load the skill, we catch 90%+ of skill loading issues early.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill Discovery and Validation
|
||||
|
||||
**Skill Discovery and Validation**
|
||||
|
||||
Claude Code skills are discovered by reading the frontmatter of SKILL.md files. The key validation points are:
|
||||
1. **YAML syntax** - Must be valid YAML between `---` delimiters
|
||||
2. **Required fields** - `name` and `description` must be present and valid
|
||||
3. **Name format** - Lowercase kebab-case, max 64 chars
|
||||
4. **Description format** - Max 1024 chars, contains action verbs
|
||||
|
||||
By validating these before even attempting to load the skill, we catch 90%+ of skill loading issues early.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill Discovery and Validation
|
||||
|
||||
**Skill Discovery and Validation**
|
||||
|
||||
Claude Code skills are discovered by reading the frontmatter of SKILL.md files. The key validation points are:
|
||||
1. **YAML syntax** - Must be valid YAML between `---` delimiters
|
||||
2. **Required fields** - `name` and `description` must be present and valid
|
||||
3. **Name format** - Lowercase kebab-case, max 64 chars
|
||||
4. **Description format** - Max 1024 chars, contains action verbs
|
||||
|
||||
By validating these before even attempting to load the skill, we catch 90%+ of skill loading issues early.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill as Documentation Pattern
|
||||
|
||||
**Skill as Documentation Pattern**
|
||||
|
||||
Notice that this skill doesn't execute code—it provides comprehensive instructions that I (Claude) interpret. The templates use Jinja2-style syntax for documentation reference, not programmatic rendering. This "skill as documentation" pattern is powerful because:
|
||||
|
||||
1. **Flexibility**: I can adapt instructions to context rather than rigidly executing code
|
||||
2. **Maintainability**: Plain markdown is easier to update than code
|
||||
3. **Clarity**: Users can read SKILL.md to understand exactly what will happen
|
||||
4. **Extensibility**: Easy to add new phases, patterns, or validations
|
||||
|
||||
The configuration files (YAML) provide tunable parameters, while SKILL.md provides the logic I execute. This separation of concerns makes the skill both powerful and maintainable.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill as Documentation Pattern
|
||||
|
||||
**Skill as Documentation Pattern**
|
||||
|
||||
Notice that this skill doesn't execute code—it provides comprehensive instructions that I (Claude) interpret. The templates use Jinja2-style syntax for documentation reference, not programmatic rendering. This "skill as documentation" pattern is powerful because:
|
||||
|
||||
1. **Flexibility**: I can adapt instructions to context rather than rigidly executing code
|
||||
2. **Maintainability**: Plain markdown is easier to update than code
|
||||
3. **Clarity**: Users can read SKILL.md to understand exactly what will happen
|
||||
4. **Extensibility**: Easy to add new phases, patterns, or validations
|
||||
|
||||
The configuration files (YAML) provide tunable parameters, while SKILL.md provides the logic I execute. This separation of concerns makes the skill both powerful and maintainable.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill as Documentation Pattern
|
||||
|
||||
**Skill as Documentation Pattern**
|
||||
|
||||
Notice that this skill doesn't execute code—it provides comprehensive instructions that I (Claude) interpret. The templates use Jinja2-style syntax for documentation reference, not programmatic rendering. This "skill as documentation" pattern is powerful because:
|
||||
|
||||
1. **Flexibility**: I can adapt instructions to context rather than rigidly executing code
|
||||
2. **Maintainability**: Plain markdown is easier to update than code
|
||||
3. **Clarity**: Users can read SKILL.md to understand exactly what will happen
|
||||
4. **Extensibility**: Easy to add new phases, patterns, or validations
|
||||
|
||||
The configuration files (YAML) provide tunable parameters, while SKILL.md provides the logic I execute. This separation of concerns makes the skill both powerful and maintainable.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill as Documentation Pattern
|
||||
|
||||
**Skill as Documentation Pattern**
|
||||
|
||||
Notice that this skill doesn't execute code—it provides comprehensive instructions that I (Claude) interpret. The templates use Jinja2-style syntax for documentation reference, not programmatic rendering. This "skill as documentation" pattern is powerful because:
|
||||
|
||||
1. **Flexibility**: I can adapt instructions to context rather than rigidly executing code
|
||||
2. **Maintainability**: Plain markdown is easier to update than code
|
||||
3. **Clarity**: Users can read SKILL.md to understand exactly what will happen
|
||||
4. **Extensibility**: Easy to add new phases, patterns, or validations
|
||||
|
||||
The configuration files (YAML) provide tunable parameters, while SKILL.md provides the logic I execute. This separation of concerns makes the skill both powerful and maintainable.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill as Documentation Pattern
|
||||
|
||||
**Skill as Documentation Pattern**
|
||||
|
||||
Notice that this skill doesn't execute code—it provides comprehensive instructions that I (Claude) interpret. The templates use Jinja2-style syntax for documentation reference, not programmatic rendering. This "skill as documentation" pattern is powerful because:
|
||||
|
||||
1. **Flexibility**: I can adapt instructions to context rather than rigidly executing code
|
||||
2. **Maintainability**: Plain markdown is easier to update than code
|
||||
3. **Clarity**: Users can read SKILL.md to understand exactly what will happen
|
||||
4. **Extensibility**: Easy to add new phases, patterns, or validations
|
||||
|
||||
The configuration files (YAML) provide tunable parameters, while SKILL.md provides the logic I execute. This separation of concerns makes the skill both powerful and maintainable.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Skill as Documentation Pattern
|
||||
|
||||
**Skill as Documentation Pattern**
|
||||
|
||||
Notice that this skill doesn't execute code—it provides comprehensive instructions that I (Claude) interpret. The templates use Jinja2-style syntax for documentation reference, not programmatic rendering. This "skill as documentation" pattern is powerful because:
|
||||
|
||||
1. **Flexibility**: I can adapt instructions to context rather than rigidly executing code
|
||||
2. **Maintainability**: Plain markdown is easier to update than code
|
||||
3. **Clarity**: Users can read SKILL.md to understand exactly what will happen
|
||||
4. **Extensibility**: Easy to add new phases, patterns, or validations
|
||||
|
||||
The configuration files (YAML) provide tunable parameters, while SKILL.md provides the logic I execute. This separation of concerns makes the skill both powerful and maintainable.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,286 @@
|
||||
# Example: Clustering Analysis Output
|
||||
|
||||
This example shows what the clustering phase produces when analyzing a project's insights.
|
||||
|
||||
## Scenario
|
||||
|
||||
A project has been using the extract-explanatory-insights hook for 2 weeks, generating 12 insights across different categories.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Discovery Summary
|
||||
|
||||
**Total Insights Found**: 12
|
||||
**Date Range**: 2025-11-01 to 2025-11-14
|
||||
**Unique Sessions**: 8
|
||||
**Categories**:
|
||||
- testing: 5 insights
|
||||
- hooks-and-events: 3 insights
|
||||
- architecture: 2 insights
|
||||
- performance: 2 insights
|
||||
|
||||
**Preview**:
|
||||
1. "Modern Testing Strategy with Testing Trophy" (testing, 2025-11-01)
|
||||
2. "Hook Deduplication Session Management" (hooks-and-events, 2025-11-03)
|
||||
3. "CPU Usage Prevention in Vitest" (testing, 2025-11-03)
|
||||
4. "BSD awk Compatibility in Hook Scripts" (hooks-and-events, 2025-11-05)
|
||||
5. "Semantic Query Priorities in React Testing Library" (testing, 2025-11-06)
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Clustering Analysis
|
||||
|
||||
### Cluster 1: Testing Strategy
|
||||
**Size**: 3 insights
|
||||
**Similarity Score**: 0.75 (high)
|
||||
**Recommended Complexity**: Standard
|
||||
**Recommended Pattern**: Validation
|
||||
|
||||
**Insights**:
|
||||
1. "Modern Testing Strategy with Testing Trophy"
|
||||
- Keywords: testing, integration, unit, e2e, trophy, kent-c-dodds
|
||||
- Category: testing
|
||||
- Date: 2025-11-01
|
||||
- Length: 156 lines
|
||||
- Has code examples: Yes
|
||||
|
||||
2. "Semantic Query Priorities in React Testing Library"
|
||||
- Keywords: testing, react, semantic, query, getByRole, accessibility
|
||||
- Category: testing
|
||||
- Date: 2025-11-06
|
||||
- Length: 89 lines
|
||||
- Has code examples: Yes
|
||||
|
||||
3. "What NOT to Test - Brittle Patterns"
|
||||
- Keywords: testing, avoid, brittle, implementation-details, user-behavior
|
||||
- Category: testing
|
||||
- Date: 2025-11-08
|
||||
- Length: 67 lines
|
||||
- Has code examples: No
|
||||
|
||||
**Shared Keywords**: testing (3), react (2), user (2), behavior (2), semantic (2)
|
||||
|
||||
**Cluster Characteristics**:
|
||||
- All in same category (testing)
|
||||
- Temporal span: 7 days
|
||||
- Common theme: User-focused testing approach
|
||||
- Total code examples: 5 blocks
|
||||
- Actionable items: 12
|
||||
|
||||
**Suggested Skill Name**: "user-focused-testing-guide"
|
||||
|
||||
**Suggested Description**: "Use PROACTIVELY when writing tests to ensure user-centric testing strategy following Testing Trophy methodology and React Testing Library best practices"
|
||||
|
||||
**Skill Structure Recommendation**:
|
||||
```
|
||||
SKILL.md sections:
|
||||
- Overview (Testing Trophy philosophy)
|
||||
- Phase 1: Query Selection (semantic queries)
|
||||
- Phase 2: Test Writing (user workflows)
|
||||
- Phase 3: Avoiding Brittle Tests
|
||||
- Important Reminders (what NOT to test)
|
||||
- Examples (from code blocks)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Cluster 2: Hook Development
|
||||
**Size**: 2 insights
|
||||
**Similarity Score**: 0.68 (medium-high)
|
||||
**Recommended Complexity**: Minimal to Standard
|
||||
**Recommended Pattern**: Phase-based
|
||||
|
||||
**Insights**:
|
||||
1. "Hook Deduplication Session Management"
|
||||
- Keywords: hook, deduplication, session, hash, state
|
||||
- Category: hooks-and-events
|
||||
- Date: 2025-11-03
|
||||
- Length: 124 lines
|
||||
- Has code examples: Yes (bash)
|
||||
|
||||
2. "BSD awk Compatibility in Hook Scripts"
|
||||
- Keywords: hook, awk, bsd, macos, compatibility, portable
|
||||
- Category: hooks-and-events
|
||||
- Date: 2025-11-05
|
||||
- Length: 78 lines
|
||||
- Has code examples: Yes (bash)
|
||||
|
||||
**Shared Keywords**: hook (2), bash (2), script (2), compatibility (2)
|
||||
|
||||
**Cluster Characteristics**:
|
||||
- Same category (hooks-and-events)
|
||||
- Temporal span: 2 days (high proximity)
|
||||
- Common theme: Hook script development best practices
|
||||
- Total code examples: 4 blocks (all bash)
|
||||
- Actionable items: 8
|
||||
|
||||
**Suggested Skill Name**: "hook-script-development-guide"
|
||||
|
||||
**Suggested Description**: "Guides Claude Code hook script development with deduplication patterns and cross-platform compatibility best practices for macOS/Linux environments"
|
||||
|
||||
**Skill Structure Recommendation**:
|
||||
```
|
||||
SKILL.md sections:
|
||||
- Overview (Hook development challenges)
|
||||
- Phase 1: Deduplication Strategy (session vs content)
|
||||
- Phase 2: Cross-Platform Compatibility (BSD awk)
|
||||
- Phase 3: Testing and Validation
|
||||
- Examples (bash scripts)
|
||||
- Templates (hook-template.sh)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Cluster 3: Performance Optimization
|
||||
**Size**: 2 insights
|
||||
**Similarity Score**: 0.62 (medium)
|
||||
**Recommended Complexity**: Minimal
|
||||
**Recommended Pattern**: Phase-based
|
||||
|
||||
**Insights**:
|
||||
1. "CPU Usage Prevention in Vitest"
|
||||
- Keywords: vitest, cpu, performance, threads, watch-mode
|
||||
- Category: testing
|
||||
- Date: 2025-11-03
|
||||
- Length: 45 lines
|
||||
- Has code examples: Yes (npm scripts)
|
||||
|
||||
2. "Bundle Size Optimization"
|
||||
- Keywords: bundle, size, webpack, optimization, tree-shaking
|
||||
- Category: performance
|
||||
- Date: 2025-11-09
|
||||
- Length: 92 lines
|
||||
- Has code examples: Yes (webpack config)
|
||||
|
||||
**Shared Keywords**: performance (2), optimization (2), build (2)
|
||||
|
||||
**Cluster Characteristics**:
|
||||
- Different categories (testing, performance)
|
||||
- Temporal span: 6 days
|
||||
- Common theme: Build/test performance
|
||||
- Total code examples: 3 blocks
|
||||
- Actionable items: 6
|
||||
|
||||
**Suggested Skill Name**: "build-performance-optimizer"
|
||||
|
||||
**Suggested Description**: "Analyzes build and test performance issues and generates optimization recommendations for Vitest test runs and webpack bundle sizes"
|
||||
|
||||
**Skill Structure Recommendation**:
|
||||
```
|
||||
SKILL.md sections:
|
||||
- Overview (Performance impact on DX)
|
||||
- Phase 1: Test Performance Analysis
|
||||
- Phase 2: Bundle Size Analysis
|
||||
- Phase 3: Optimization Implementation
|
||||
- Important Reminders (check before test, monitor bundle)
|
||||
- Examples (npm scripts, webpack config)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Standalone Insights
|
||||
|
||||
#### Standalone 1: "Hook State Management Patterns"
|
||||
**Quality Score**: 0.85 (high - qualifies for standalone skill)
|
||||
**Category**: hooks-and-events
|
||||
**Date**: 2025-11-07
|
||||
**Length**: 134 lines
|
||||
**Code Examples**: Yes (3 blocks)
|
||||
|
||||
**Why Standalone**:
|
||||
- Doesn't cluster with other hook insights (different focus)
|
||||
- High quality with comprehensive coverage
|
||||
- Self-contained topic (state management)
|
||||
- Multiple actionable patterns
|
||||
|
||||
**Suggested Skill Name**: "hook-state-manager"
|
||||
|
||||
**Suggested Description**: "Automates state management setup for Claude Code hooks with persistent storage, cleanup, and safe concurrency patterns"
|
||||
|
||||
---
|
||||
|
||||
#### Standalone 2: "Architecture Decision Records"
|
||||
**Quality Score**: 0.82 (high - qualifies for standalone skill)
|
||||
**Category**: architecture
|
||||
**Date**: 2025-11-12
|
||||
**Length**: 156 lines
|
||||
**Code Examples**: Yes (template)
|
||||
|
||||
**Why Standalone**:
|
||||
- Unique topic (no other architecture insights)
|
||||
- High quality with complete template
|
||||
- Valuable for documentation
|
||||
- Industry best practice
|
||||
|
||||
**Suggested Skill Name**: "adr-documentation-helper"
|
||||
|
||||
**Suggested Description**: "Guides creation of Architecture Decision Records (ADRs) following industry standards with templates and integration with project documentation"
|
||||
|
||||
---
|
||||
|
||||
### Low-Quality Insights (Not Recommended for Skills)
|
||||
|
||||
#### "Git Branch Naming Convention"
|
||||
**Quality Score**: 0.42 (low)
|
||||
**Category**: version-control
|
||||
**Reason for Exclusion**: Too simple, covered by existing conventions, no unique value
|
||||
|
||||
#### "TypeScript Strict Mode Benefits"
|
||||
**Quality Score**: 0.38 (low)
|
||||
**Category**: typescript
|
||||
**Reason for Exclusion**: Common knowledge, well-documented elsewhere, not actionable enough
|
||||
|
||||
---
|
||||
|
||||
## User Decision Points
|
||||
|
||||
At this stage, the skill would present the following options to the user:
|
||||
|
||||
**Option 1: Generate All Recommended Skills** (5 skills)
|
||||
- user-focused-testing-guide (Cluster 1)
|
||||
- hook-script-development-guide (Cluster 2)
|
||||
- build-performance-optimizer (Cluster 3)
|
||||
- hook-state-manager (Standalone 1)
|
||||
- adr-documentation-helper (Standalone 2)
|
||||
|
||||
**Option 2: Select Specific Skills**
|
||||
- User picks which clusters/standalones to convert
|
||||
|
||||
**Option 3: Modify Clusters**
|
||||
- Split large clusters
|
||||
- Merge small clusters
|
||||
- Recategorize insights
|
||||
- Adjust complexity levels
|
||||
|
||||
**Option 4: Tune Thresholds and Retry**
|
||||
- Increase cluster_minimum (0.6 → 0.7) for tighter clusters
|
||||
- Decrease standalone_quality (0.8 → 0.7) for more standalone skills
|
||||
|
||||
---
|
||||
|
||||
## Proceeding to Phase 3
|
||||
|
||||
If user selects "user-focused-testing-guide" to generate, the skill would proceed to Phase 3: Interactive Skill Design with the following proposal:
|
||||
|
||||
**Skill Design Proposal**:
|
||||
- Name: `user-focused-testing-guide`
|
||||
- Description: "Use PROACTIVELY when writing tests to ensure user-centric testing strategy following Testing Trophy methodology and React Testing Library best practices"
|
||||
- Complexity: Standard
|
||||
- Pattern: Validation
|
||||
- Structure:
|
||||
- SKILL.md with validation workflow
|
||||
- data/insights-reference.md with 3 source insights
|
||||
- examples/query-examples.md with semantic query patterns
|
||||
- templates/test-checklist.md with testing checklist
|
||||
|
||||
User can then customize before generation begins.
|
||||
|
||||
---
|
||||
|
||||
**This example demonstrates**:
|
||||
1. How clustering groups related insights
|
||||
2. What information is presented for each cluster
|
||||
3. How standalone insights are identified
|
||||
4. Why some insights are excluded
|
||||
5. What decisions users can make
|
||||
6. How the process flows into Phase 3
|
||||
@@ -0,0 +1,24 @@
|
||||
# Changelog
|
||||
|
||||
## [0.1.0] - 2025-11-16
|
||||
|
||||
### Added
|
||||
- Initial release
|
||||
- Generated from 1 insight (Hook Deduplication Session Management)
|
||||
- Phase 1: Choose Deduplication Strategy
|
||||
- Phase 2: Implement Content-Based Deduplication
|
||||
- Phase 3: Implement Hash Rotation
|
||||
- Phase 4: Testing and Validation
|
||||
- Code examples for bash hook implementation
|
||||
- Troubleshooting section
|
||||
|
||||
### Features
|
||||
- Content-based deduplication using SHA256 hashes
|
||||
- Session-independent duplicate detection
|
||||
- Efficient hash storage with rotation
|
||||
- State management best practices
|
||||
|
||||
### Generated By
|
||||
- insight-skill-generator v0.1.0
|
||||
- Source category: hooks-and-events
|
||||
- Original insight date: 2025-11-03
|
||||
@@ -0,0 +1,51 @@
|
||||
# Hook Deduplication Guide
|
||||
|
||||
Implement robust content-based deduplication for Claude Code hooks.
|
||||
|
||||
## Overview
|
||||
|
||||
This skill guides you through implementing SHA256 hash-based deduplication to prevent duplicate insights or data from being stored across sessions.
|
||||
|
||||
## When to Use
|
||||
|
||||
**Trigger Phrases**:
|
||||
- "implement hook deduplication"
|
||||
- "prevent duplicate insights in hooks"
|
||||
- "content-based deduplication for hooks"
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Test the skill
|
||||
You: "I need to add deduplication to my hook to prevent storing the same insight twice"
|
||||
|
||||
Claude: [Activates hook-deduplication-guide]
|
||||
- Explains content-based vs session-based strategies
|
||||
- Guides implementation of SHA256 hashing
|
||||
- Shows hash rotation to prevent file bloat
|
||||
- Provides testing validation
|
||||
```
|
||||
|
||||
## What You'll Get
|
||||
|
||||
- Content-based deduplication using SHA256
|
||||
- Efficient hash storage with rotation
|
||||
- Testing and validation guidance
|
||||
- Best practices for hook state management
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# This is an example generated by insight-skill-generator
|
||||
# Copy to your skills directory if you want to use it
|
||||
cp -r examples/example-generated-skill ~/.claude/skills/hook-deduplication-guide
|
||||
```
|
||||
|
||||
## Learn More
|
||||
|
||||
See [SKILL.md](SKILL.md) for complete workflow documentation.
|
||||
|
||||
---
|
||||
|
||||
**Generated by**: insight-skill-generator v0.1.0
|
||||
**Source**: 1 insight from hooks-and-events category
|
||||
@@ -0,0 +1,342 @@
|
||||
---
|
||||
name: hook-deduplication-guide
|
||||
description: Use PROACTIVELY when developing Claude Code hooks to implement content-based deduplication and prevent duplicate insight storage across sessions
|
||||
---
|
||||
|
||||
# Hook Deduplication Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This skill guides you through implementing robust deduplication for Claude Code hooks, using content-based hashing instead of session-based tracking. Prevents duplicate insights from being stored while allowing multiple unique insights per session.
|
||||
|
||||
**Based on 1 insight**:
|
||||
- Hook Deduplication Session Management (hooks-and-events, 2025-11-03)
|
||||
|
||||
**Key Capabilities**:
|
||||
- Content-based deduplication using SHA256 hashes
|
||||
- Session-independent duplicate detection
|
||||
- Efficient hash storage with rotation
|
||||
- State management best practices
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Trigger Phrases**:
|
||||
- "implement hook deduplication"
|
||||
- "prevent duplicate insights in hooks"
|
||||
- "content-based deduplication for hooks"
|
||||
- "hook state management patterns"
|
||||
|
||||
**Use Cases**:
|
||||
- Developing new Claude Code hooks that store data
|
||||
- Refactoring hooks to prevent duplicates
|
||||
- Implementing efficient state management for hooks
|
||||
- Debugging duplicate data issues in hooks
|
||||
|
||||
**Do NOT use when**:
|
||||
- Creating hooks that don't store data (read-only hooks)
|
||||
- Session-based deduplication is actually desired
|
||||
- Hook doesn't run frequently enough to need deduplication
|
||||
|
||||
## Response Style
|
||||
|
||||
Educational and practical - explain the why behind content-based vs. session-based deduplication, then guide implementation with code examples.
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Choose Deduplication Strategy
|
||||
|
||||
**Purpose**: Determine whether content-based or session-based deduplication is appropriate.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Assess hook behavior**:
|
||||
- How often does the hook run? (per message, per session, per event)
|
||||
- What data is being stored? (insights, logs, metrics)
|
||||
- Is the same content likely to appear across sessions?
|
||||
|
||||
2. **Evaluate deduplication needs**:
|
||||
- **Content-based**: Use when the same insight/data might appear in different sessions
|
||||
- Example: Extract-explanatory-insights hook (same insight might appear in multiple conversations)
|
||||
- **Session-based**: Use when duplicates should only be prevented within a session
|
||||
- Example: Error logging (same error in different sessions should be logged)
|
||||
|
||||
3. **Recommend strategy**:
|
||||
- For insights/lessons-learned: Content-based (SHA256 hashing)
|
||||
- For session logs/events: Session-based (session ID tracking)
|
||||
- For unique events: No deduplication needed
|
||||
|
||||
**Output**: Clear recommendation on deduplication strategy.
|
||||
|
||||
**Common Issues**:
|
||||
- **Unsure which to use**: Default to content-based for data that's meant to be unique (insights, documentation)
|
||||
- **Performance concerns**: Content-based hashing is fast (<1ms for typical content)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Implement Content-Based Deduplication
|
||||
|
||||
**Purpose**: Set up SHA256 hash-based deduplication with state management.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Create state directory**:
|
||||
```bash
|
||||
mkdir -p ~/.claude/state/hook-state/
|
||||
```
|
||||
|
||||
2. **Initialize hash storage file**:
|
||||
```bash
|
||||
HASH_FILE="$HOME/.claude/state/hook-state/content-hashes.txt"
|
||||
touch "$HASH_FILE"
|
||||
```
|
||||
|
||||
3. **Implement hash generation**:
|
||||
```bash
|
||||
# Generate SHA256 hash of content
|
||||
compute_content_hash() {
|
||||
local content="$1"
|
||||
echo -n "$content" | sha256sum | awk '{print $1}'
|
||||
}
|
||||
```
|
||||
|
||||
4. **Check for duplicates**:
|
||||
```bash
|
||||
# Returns 0 if content is new, 1 if duplicate
|
||||
is_duplicate() {
|
||||
local content="$1"
|
||||
local content_hash=$(compute_content_hash "$content")
|
||||
|
||||
if grep -Fxq "$content_hash" "$HASH_FILE"; then
|
||||
return 1 # Duplicate found
|
||||
else
|
||||
return 0 # New content
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
5. **Store hash after processing**:
|
||||
```bash
|
||||
store_content_hash() {
|
||||
local content="$1"
|
||||
local content_hash=$(compute_content_hash "$content")
|
||||
echo "$content_hash" >> "$HASH_FILE"
|
||||
}
|
||||
```
|
||||
|
||||
6. **Integrate into hook**:
|
||||
```bash
|
||||
# In your hook script
|
||||
content="extracted insight or data"
|
||||
|
||||
if is_duplicate "$content"; then
|
||||
# Skip - duplicate content
|
||||
echo "Duplicate detected, skipping..." >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Process new content
|
||||
process_content "$content"
|
||||
|
||||
# Store hash to prevent future duplicates
|
||||
store_content_hash "$content"
|
||||
```
|
||||
|
||||
**Output**: Working content-based deduplication in your hook.
|
||||
|
||||
**Common Issues**:
|
||||
- **Hash file grows too large**: Implement rotation (see Phase 3)
|
||||
- **False positives**: Ensure content normalization (whitespace, formatting)
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Implement Hash Rotation
|
||||
|
||||
**Purpose**: Prevent hash file from growing indefinitely.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Set rotation limit**:
|
||||
```bash
|
||||
MAX_HASHES=10000 # Keep last 10,000 hashes
|
||||
```
|
||||
|
||||
2. **Implement rotation logic**:
|
||||
```bash
|
||||
rotate_hash_file() {
|
||||
local hash_file="$1"
|
||||
local max_hashes="${2:-10000}"
|
||||
|
||||
# Count current hashes
|
||||
local current_count=$(wc -l < "$hash_file")
|
||||
|
||||
# Rotate if needed
|
||||
if [ "$current_count" -gt "$max_hashes" ]; then
|
||||
tail -n "$max_hashes" "$hash_file" > "${hash_file}.tmp"
|
||||
mv "${hash_file}.tmp" "$hash_file"
|
||||
echo "Rotated hash file: kept last $max_hashes hashes" >&2
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
3. **Call rotation periodically**:
|
||||
```bash
|
||||
# After storing new hash
|
||||
store_content_hash "$content"
|
||||
rotate_hash_file "$HASH_FILE" 10000
|
||||
```
|
||||
|
||||
**Output**: Self-maintaining hash storage with bounded size.
|
||||
|
||||
**Common Issues**:
|
||||
- **Rotation too aggressive**: Increase MAX_HASHES
|
||||
- **Rotation too infrequent**: Consider checking count before every append
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Testing and Validation
|
||||
|
||||
**Purpose**: Verify deduplication works correctly.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Test duplicate detection**:
|
||||
```bash
|
||||
# First run - should process
|
||||
echo "Test insight" | your_hook.sh
|
||||
# Check: Content was processed
|
||||
|
||||
# Second run - should skip
|
||||
echo "Test insight" | your_hook.sh
|
||||
# Check: Duplicate detected message
|
||||
```
|
||||
|
||||
2. **Test multiple unique items**:
|
||||
```bash
|
||||
echo "Insight 1" | your_hook.sh # Processed
|
||||
echo "Insight 2" | your_hook.sh # Processed
|
||||
echo "Insight 3" | your_hook.sh # Processed
|
||||
echo "Insight 1" | your_hook.sh # Skipped (duplicate)
|
||||
```
|
||||
|
||||
3. **Verify hash file**:
|
||||
```bash
|
||||
cat ~/.claude/state/hook-state/content-hashes.txt
|
||||
# Should show 3 unique hashes (not 4)
|
||||
```
|
||||
|
||||
4. **Test rotation**:
|
||||
```bash
|
||||
# Generate more than MAX_HASHES entries
|
||||
for i in {1..10500}; do
|
||||
echo "Insight $i" | your_hook.sh
|
||||
done
|
||||
|
||||
# Verify file size bounded
|
||||
wc -l ~/.claude/state/hook-state/content-hashes.txt
|
||||
# Should be ~10000, not 10500
|
||||
```
|
||||
|
||||
**Output**: Confirmed working deduplication with proper rotation.
|
||||
|
||||
---
|
||||
|
||||
## Reference Materials
|
||||
|
||||
- [Original Insight](data/insights-reference.md) - Full context on hook deduplication patterns
|
||||
|
||||
---
|
||||
|
||||
## Important Reminders
|
||||
|
||||
- **Use content-based deduplication for insights/documentation** - prevents duplicates across sessions
|
||||
- **Use session-based deduplication for logs/events** - same event in different sessions is meaningful
|
||||
- **Normalize content before hashing** - whitespace differences shouldn't create false negatives
|
||||
- **Implement rotation** - prevent unbounded hash file growth
|
||||
- **Hash storage location**: `~/.claude/state/hook-state/` (not project-specific)
|
||||
- **SHA256 is fast** - no performance concerns for typical hook data
|
||||
- **Test both paths** - verify both new content and duplicates work correctly
|
||||
|
||||
**Warnings**:
|
||||
- ⚠️ **Do not use session ID alone** - prevents same insight in different sessions from being stored
|
||||
- ⚠️ **Do not skip rotation** - hash file will grow indefinitely
|
||||
- ⚠️ **Do not hash before normalization** - formatting changes will cause false negatives
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Choose the Right Strategy**: Content-based for unique data, session-based for session-specific events
|
||||
2. **Normalize Before Hashing**: Strip whitespace, lowercase if appropriate, consistent formatting
|
||||
3. **Efficient Storage**: Use grep -Fxq for fast hash lookups (fixed-string, line-match, quiet)
|
||||
4. **Bounded Growth**: Implement rotation to prevent file bloat
|
||||
5. **Clear Logging**: Log when duplicates are detected for debugging
|
||||
6. **State Location**: Use ~/.claude/state/hook-state/ for cross-project state
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Duplicates not being detected
|
||||
|
||||
**Symptoms**: Same content processed multiple times
|
||||
|
||||
**Solution**:
|
||||
1. Check hash file exists and is writable
|
||||
2. Verify store_content_hash is called after processing
|
||||
3. Check content normalization (whitespace differences)
|
||||
4. Verify grep command uses -Fxq flags
|
||||
|
||||
**Prevention**: Test deduplication immediately after implementation
|
||||
|
||||
---
|
||||
|
||||
### Hash file growing too large
|
||||
|
||||
**Symptoms**: Hash file exceeds MAX_HASHES significantly
|
||||
|
||||
**Solution**:
|
||||
1. Verify rotate_hash_file is called
|
||||
2. Check MAX_HASHES value is reasonable
|
||||
3. Manually rotate if needed: `tail -n 10000 hashes.txt > hashes.tmp && mv hashes.tmp hashes.txt`
|
||||
|
||||
**Prevention**: Call rotation after every hash storage
|
||||
|
||||
---
|
||||
|
||||
### False positives (new content marked as duplicate)
|
||||
|
||||
**Symptoms**: Different content being skipped
|
||||
|
||||
**Solution**:
|
||||
1. Check for hash collisions (extremely unlikely with SHA256)
|
||||
2. Verify content is actually different
|
||||
3. Check normalization isn't too aggressive
|
||||
4. Review recent hashes in file
|
||||
|
||||
**Prevention**: Use consistent normalization, test with diverse content
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
After implementing deduplication:
|
||||
1. Monitor hash file growth over time
|
||||
2. Tune MAX_HASHES based on usage patterns
|
||||
3. Consider adding metrics (duplicates prevented, storage size)
|
||||
4. Share pattern with team for other hooks
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
**Source Insights**:
|
||||
- Session: abc123-session-id
|
||||
- Date: 2025-11-03
|
||||
- Category: hooks-and-events
|
||||
- File: docs/lessons-learned/hooks-and-events/2025-11-03-hook-deduplication.md
|
||||
|
||||
**Skill Version**: 0.1.0
|
||||
**Generated**: 2025-11-16
|
||||
**Last Updated**: 2025-11-16
|
||||
@@ -0,0 +1,116 @@
|
||||
# Insights Reference: hook-deduplication-guide
|
||||
|
||||
This document contains the original insight from Claude Code's Explanatory output style that was used to create the **Hook Deduplication Guide** skill.
|
||||
|
||||
## Overview
|
||||
|
||||
**Total Insights**: 1
|
||||
**Date Range**: 2025-11-03
|
||||
**Categories**: hooks-and-events
|
||||
**Sessions**: 1 unique session
|
||||
|
||||
---
|
||||
|
||||
## 1. Hook Deduplication Session Management
|
||||
|
||||
**Metadata**:
|
||||
- **Date**: 2025-11-03
|
||||
- **Category**: hooks-and-events
|
||||
- **Session**: abc123-session-id
|
||||
- **Source File**: docs/lessons-learned/hooks-and-events/2025-11-03-hook-deduplication.md
|
||||
|
||||
**Original Content**:
|
||||
|
||||
The extract-explanatory-insights hook initially used session-based deduplication, which prevented multiple insights from the same session from being stored. However, this created a limitation: if the same valuable insight appeared in different sessions, only the first one would be saved.
|
||||
|
||||
By switching to content-based deduplication using SHA256 hashing, we can:
|
||||
|
||||
1. **Allow multiple unique insights per session** - Different insights in the same conversation are all preserved
|
||||
2. **Prevent true duplicates across sessions** - The same insight appearing in multiple conversations is stored only once
|
||||
3. **Maintain efficient storage** - Hash file rotation keeps storage bounded
|
||||
|
||||
The implementation involves:
|
||||
|
||||
**Hash Generation**:
|
||||
```bash
|
||||
compute_content_hash() {
|
||||
local content="$1"
|
||||
echo -n "$content" | sha256sum | awk '{print $1}'
|
||||
}
|
||||
```
|
||||
|
||||
**Duplicate Detection**:
|
||||
```bash
|
||||
is_duplicate() {
|
||||
local content="$1"
|
||||
local content_hash=$(compute_content_hash "$content")
|
||||
|
||||
if grep -Fxq "$content_hash" "$HASH_FILE"; then
|
||||
return 1 # Duplicate
|
||||
else
|
||||
return 0 # New content
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
**Hash Storage with Rotation**:
|
||||
```bash
|
||||
store_content_hash() {
|
||||
local content="$1"
|
||||
local content_hash=$(compute_content_hash "$content")
|
||||
echo "$content_hash" >> "$HASH_FILE"
|
||||
|
||||
# Rotate if file exceeds MAX_HASHES
|
||||
local count=$(wc -l < "$HASH_FILE")
|
||||
if [ "$count" -gt 10000 ]; then
|
||||
tail -n 10000 "$HASH_FILE" > "${HASH_FILE}.tmp"
|
||||
mv "${HASH_FILE}.tmp" "$HASH_FILE"
|
||||
fi
|
||||
}
|
||||
```
|
||||
|
||||
This approach provides the best of both worlds: session independence and true deduplication based on content, not session boundaries.
|
||||
|
||||
---
|
||||
|
||||
## How This Insight Informs the Skill
|
||||
|
||||
### Hook Deduplication Session Management → Phase-Based Workflow
|
||||
|
||||
The insight's structure (problem → solution → implementation) maps directly to the skill's phases:
|
||||
|
||||
- **Problem Description** → Phase 1: Choose Deduplication Strategy
|
||||
- Explains why session-based is insufficient
|
||||
- Defines when content-based is needed
|
||||
|
||||
- **Solution Explanation** → Phase 2: Implement Content-Based Deduplication
|
||||
- Hash generation logic
|
||||
- Duplicate detection mechanism
|
||||
- State file management
|
||||
|
||||
- **Implementation Details** → Phase 3: Implement Hash Rotation
|
||||
- Rotation logic to prevent unbounded growth
|
||||
- MAX_HASHES configuration
|
||||
|
||||
- **Code Examples** → All phases
|
||||
- Bash functions extracted and integrated into workflow steps
|
||||
|
||||
---
|
||||
|
||||
## Additional Context
|
||||
|
||||
**Why This Insight Was Selected**:
|
||||
|
||||
This insight was selected for skill generation because it:
|
||||
1. Provides a complete, actionable pattern
|
||||
2. Includes working code examples
|
||||
3. Solves a common problem in hook development
|
||||
4. Is generally applicable (not project-specific)
|
||||
5. Has clear benefits over the naive approach
|
||||
|
||||
**Quality Score**: 0.85 (high - qualified for standalone skill)
|
||||
|
||||
---
|
||||
|
||||
**Generated**: 2025-11-16
|
||||
**Last Updated**: 2025-11-16
|
||||
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"name": "hook-deduplication-guide",
|
||||
"version": "0.1.0",
|
||||
"description": "Use PROACTIVELY when developing Claude Code hooks to implement content-based deduplication and prevent duplicate insight storage across sessions",
|
||||
"type": "skill",
|
||||
"author": "Connor",
|
||||
"category": "productivity",
|
||||
"tags": [
|
||||
"hooks",
|
||||
"deduplication",
|
||||
"state-management",
|
||||
"bash",
|
||||
"generated-from-insights"
|
||||
]
|
||||
}
|
||||
72
skills/insight-skill-generator/reference/troubleshooting.md
Normal file
72
skills/insight-skill-generator/reference/troubleshooting.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
## No insights found
|
||||
|
||||
**Symptoms**: Phase 1 reports 0 insights
|
||||
|
||||
**Solution**:
|
||||
1. Verify `docs/lessons-learned/` exists in project
|
||||
2. Check for alternative locations (ask user)
|
||||
3. Verify insights were actually generated by extract-explanatory-insights hook
|
||||
4. Check file naming pattern matches YYYY-MM-DD-*.md
|
||||
|
||||
**Prevention**: Set up extract-explanatory-insights hook if not already configured
|
||||
|
||||
---
|
||||
|
||||
## All insights cluster into one giant skill
|
||||
|
||||
**Symptoms**: Phase 2 creates one cluster with 10+ insights
|
||||
|
||||
**Solution**:
|
||||
1. Increase clustering threshold (e.g., 0.6 → 0.7)
|
||||
2. Enable sub-clustering (split by sub-topics or time periods)
|
||||
3. Manually split cluster in Phase 2 user review
|
||||
4. Create mode-based skill with different modes for different sub-topics
|
||||
|
||||
**Prevention**: Tune clustering-config.yaml thresholds for your domain
|
||||
|
||||
---
|
||||
|
||||
## Generated skill doesn't load
|
||||
|
||||
**Symptoms**: Skill not recognized by Claude Code after installation
|
||||
|
||||
**Solution**:
|
||||
1. Check YAML frontmatter syntax (no tabs, proper dashes)
|
||||
2. Verify name field is lowercase kebab-case
|
||||
3. Check description doesn't contain special characters that break parsing
|
||||
4. Restart Claude Code session
|
||||
5. Check skill file permissions (should be readable)
|
||||
|
||||
**Prevention**: Always run validation in Phase 4 before installation
|
||||
|
||||
---
|
||||
|
||||
## Trigger phrases don't activate skill
|
||||
|
||||
**Symptoms**: Using trigger phrase doesn't invoke the skill
|
||||
|
||||
**Solution**:
|
||||
1. Make trigger phrases more specific (avoid overly generic phrases)
|
||||
2. Include domain keywords in trigger phrases
|
||||
3. Add "PROACTIVELY when" to description for auto-triggering
|
||||
4. Try exact phrase match vs. semantic match
|
||||
5. Check for conflicts with built-in commands or other skills
|
||||
|
||||
**Prevention**: Test trigger phrases in Phase 5 before finalizing
|
||||
|
||||
---
|
||||
|
||||
## Generated content quality is low
|
||||
|
||||
**Symptoms**: SKILL.md is vague, missing details, or poorly organized
|
||||
|
||||
**Solution**:
|
||||
1. Check insight quality (garbage in, garbage out)
|
||||
2. Manually edit SKILL.md to improve clarity
|
||||
3. Add more examples and context
|
||||
4. Reorganize sections for better flow
|
||||
5. Iterate to version 0.2.0 with improvements
|
||||
|
||||
**Prevention**: Filter low-quality insights in Phase 2, prioritize insights with clear action items
|
||||
@@ -0,0 +1,211 @@
|
||||
# Template: Insight-Based Skill (SKILL.md)
|
||||
|
||||
This template shows the recommended structure for skills generated from insights.
|
||||
Use this as a reference pattern when creating SKILL.md files.
|
||||
|
||||
---
|
||||
name: {{ skill_name }}
|
||||
description: {{ description }}
|
||||
---
|
||||
|
||||
# {{ skill_title }}
|
||||
|
||||
## Overview
|
||||
|
||||
{{ overview_text }}
|
||||
|
||||
**Based on {{ insight_count }} insight(s)**:
|
||||
{% for insight in insights %}
|
||||
- {{ insight.title }} ({{ insight.category }}, {{ insight.date }})
|
||||
{% endfor %}
|
||||
|
||||
**Key Capabilities**:
|
||||
{% for capability in capabilities %}
|
||||
- {{ capability }}
|
||||
{% endfor %}
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Trigger Phrases**:
|
||||
{% for trigger in trigger_phrases %}
|
||||
- "{{ trigger }}"
|
||||
{% endfor %}
|
||||
|
||||
**Use Cases**:
|
||||
{% for use_case in use_cases %}
|
||||
- {{ use_case }}
|
||||
{% endfor %}
|
||||
|
||||
**Do NOT use when**:
|
||||
{% for anti_use_case in anti_use_cases %}
|
||||
- {{ anti_use_case }}
|
||||
{% endfor %}
|
||||
|
||||
## Response Style
|
||||
|
||||
{{ response_style }}
|
||||
|
||||
---
|
||||
|
||||
{% if pattern == 'phase-based' %}
|
||||
## Workflow
|
||||
|
||||
{% for phase in phases %}
|
||||
### Phase {{ loop.index }}: {{ phase.name }}
|
||||
|
||||
**Purpose**: {{ phase.purpose }}
|
||||
|
||||
**Steps**:
|
||||
{% for step in phase.steps %}
|
||||
{{ loop.index }}. {{ step }}
|
||||
{% endfor %}
|
||||
|
||||
**Output**: {{ phase.output }}
|
||||
|
||||
{% if phase.common_issues %}
|
||||
**Common Issues**:
|
||||
{% for issue in phase.common_issues %}
|
||||
- {{ issue }}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
{% endfor %}
|
||||
|
||||
{% elif pattern == 'mode-based' %}
|
||||
## Mode Selection
|
||||
|
||||
This skill operates in {{ modes|length }} distinct modes. Choose based on your needs:
|
||||
|
||||
{% for mode in modes %}
|
||||
### Mode {{ loop.index }}: {{ mode.name }}
|
||||
|
||||
**When to use**: {{ mode.when_to_use }}
|
||||
|
||||
**Steps**:
|
||||
{% for step in mode.steps %}
|
||||
{{ loop.index }}. {{ step }}
|
||||
{% endfor %}
|
||||
|
||||
**Output**: {{ mode.output }}
|
||||
|
||||
{% endfor %}
|
||||
|
||||
{% elif pattern == 'validation' %}
|
||||
## Validation Workflow
|
||||
|
||||
### Analysis Phase
|
||||
|
||||
**Steps**:
|
||||
{% for step in analysis_steps %}
|
||||
{{ loop.index }}. {{ step }}
|
||||
{% endfor %}
|
||||
|
||||
### Issue Detection
|
||||
|
||||
**Checks performed**:
|
||||
{% for check in checks %}
|
||||
- {{ check }}
|
||||
{% endfor %}
|
||||
|
||||
### Recommendations
|
||||
|
||||
**Output format**:
|
||||
- Issue severity (Critical/High/Medium/Low)
|
||||
- Issue description
|
||||
- Recommended fix
|
||||
- Code examples (if applicable)
|
||||
|
||||
{% endif %}
|
||||
|
||||
---
|
||||
|
||||
## Reference Materials
|
||||
|
||||
{% if has_data_dir %}
|
||||
Detailed reference information is available in:
|
||||
- [Insights Reference](data/insights-reference.md) - Original insights that informed this skill
|
||||
{% if has_additional_data %}
|
||||
{% for data_file in data_files %}
|
||||
- [{{ data_file.title }}](data/{{ data_file.filename }}) - {{ data_file.description }}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
{% endif %}
|
||||
|
||||
{% if has_examples %}
|
||||
**Examples**:
|
||||
{% for example in examples %}
|
||||
- [{{ example.title }}](examples/{{ example.filename }}) - {{ example.description }}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
{% if has_templates %}
|
||||
**Templates**:
|
||||
{% for template in templates %}
|
||||
- [{{ template.title }}](templates/{{ template.filename }}) - {{ template.description }}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
---
|
||||
|
||||
## Important Reminders
|
||||
|
||||
{% for reminder in important_reminders %}
|
||||
- {{ reminder }}
|
||||
{% endfor %}
|
||||
|
||||
{% if warnings %}
|
||||
**Warnings**:
|
||||
{% for warning in warnings %}
|
||||
- ⚠️ {{ warning }}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
{% for practice in best_practices %}
|
||||
{{ loop.index }}. **{{ practice.title }}**: {{ practice.description }}
|
||||
{% endfor %}
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
{% for issue in troubleshooting %}
|
||||
### {{ issue.problem }}
|
||||
|
||||
**Symptoms**: {{ issue.symptoms }}
|
||||
|
||||
**Solution**: {{ issue.solution }}
|
||||
|
||||
{% if issue.prevention %}
|
||||
**Prevention**: {{ issue.prevention }}
|
||||
{% endif %}
|
||||
|
||||
{% endfor %}
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
After using this skill:
|
||||
{% for next_step in next_steps %}
|
||||
{{ loop.index }}. {{ next_step }}
|
||||
{% endfor %}
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
**Source Insights**:
|
||||
{% for insight in insights %}
|
||||
- Session: {{ insight.session_id }}
|
||||
- Date: {{ insight.date }}
|
||||
- Category: {{ insight.category }}
|
||||
- File: {{ insight.source_file }}
|
||||
{% endfor %}
|
||||
|
||||
**Skill Version**: {{ version }}
|
||||
**Generated**: {{ generated_date }}
|
||||
**Last Updated**: {{ updated_date }}
|
||||
@@ -0,0 +1,71 @@
|
||||
# Template: Actionable Checklist (templates/checklist.md)
|
||||
|
||||
This template creates actionable checklists from insight action items.
|
||||
|
||||
# {{ skill_title }} - Checklist
|
||||
|
||||
This checklist extracts actionable items from the insights that inform this skill.
|
||||
|
||||
## Overview
|
||||
|
||||
Use this checklist to ensure you've applied all recommendations from the **{{ skill_title }}** skill.
|
||||
|
||||
**Total Items**: {{ total_items }}
|
||||
**Estimated Time**: {{ estimated_time }}
|
||||
|
||||
---
|
||||
|
||||
{% for section in sections %}
|
||||
## {{ section.name }}
|
||||
|
||||
{{ section.description }}
|
||||
|
||||
{% for item in section.items %}
|
||||
- [ ] {{ item.description }}
|
||||
{% if item.details %}
|
||||
- Details: {{ item.details }}
|
||||
{% endif %}
|
||||
{% if item.why %}
|
||||
- Why: {{ item.why }}
|
||||
{% endif %}
|
||||
{% if item.how %}
|
||||
- How: {{ item.how }}
|
||||
{% endif %}
|
||||
{% if item.validation %}
|
||||
- Validation: {{ item.validation }}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
{% if section.notes %}
|
||||
**Notes**:
|
||||
{% for note in section.notes %}
|
||||
- {{ note }}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
---
|
||||
|
||||
{% endfor %}
|
||||
|
||||
## Verification
|
||||
|
||||
After completing this checklist:
|
||||
|
||||
{% for verification in verifications %}
|
||||
- [ ] {{ verification }}
|
||||
{% endfor %}
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
{% for mistake in common_mistakes %}
|
||||
{{ loop.index }}. **{{ mistake.what }}**
|
||||
- How to avoid: {{ mistake.how_to_avoid }}
|
||||
{% if mistake.fix %}
|
||||
- If you made this mistake: {{ mistake.fix }}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
---
|
||||
|
||||
**Source**: Generated from {{ insight_count }} insight(s)
|
||||
**Last Updated**: {{ updated_date }}
|
||||
@@ -0,0 +1,96 @@
|
||||
# Template: Insights Reference (data/insights-reference.md)
|
||||
|
||||
This template consolidates the original insights that informed a generated skill.
|
||||
|
||||
# Insights Reference: {{ skill_name }}
|
||||
|
||||
This document contains the original insights from Claude Code's Explanatory output style that were used to create the **{{ skill_title }}** skill.
|
||||
|
||||
## Overview
|
||||
|
||||
**Total Insights**: {{ insight_count }}
|
||||
**Date Range**: {{ earliest_date }} to {{ latest_date }}
|
||||
**Categories**: {{ categories|join(', ') }}
|
||||
**Sessions**: {{ session_count }} unique session(s)
|
||||
|
||||
---
|
||||
|
||||
{% for insight in insights %}
|
||||
## {{ loop.index }}. {{ insight.title }}
|
||||
|
||||
**Metadata**:
|
||||
- **Date**: {{ insight.date }}
|
||||
- **Category**: {{ insight.category }}
|
||||
- **Session**: {{ insight.session_id }}
|
||||
- **Source File**: {{ insight.source_file }}
|
||||
|
||||
**Original Content**:
|
||||
|
||||
{{ insight.content }}
|
||||
|
||||
{% if insight.code_examples %}
|
||||
**Code Examples from this Insight**:
|
||||
|
||||
{% for example in insight.code_examples %}
|
||||
```{{ example.language }}
|
||||
{{ example.code }}
|
||||
```
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
|
||||
{% if insight.related_insights %}
|
||||
**Related Insights**: {{ insight.related_insights|join(', ') }}
|
||||
{% endif %}
|
||||
|
||||
---
|
||||
|
||||
{% endfor %}
|
||||
|
||||
## Insight Clustering Analysis
|
||||
|
||||
**Similarity Scores**:
|
||||
{% for cluster in clusters %}
|
||||
- Cluster {{ loop.index }}: {{ cluster.insights|join(', ') }} (score: {{ cluster.score }})
|
||||
{% endfor %}
|
||||
|
||||
**Common Keywords**:
|
||||
{% for keyword in common_keywords %}
|
||||
- {{ keyword.word }} (frequency: {{ keyword.count }})
|
||||
{% endfor %}
|
||||
|
||||
**Category Distribution**:
|
||||
{% for category, count in category_distribution.items() %}
|
||||
- {{ category }}: {{ count }} insight(s)
|
||||
{% endfor %}
|
||||
|
||||
---
|
||||
|
||||
## How These Insights Inform the Skill
|
||||
|
||||
{% for mapping in insight_mappings %}
|
||||
### {{ mapping.insight_title }} → {{ mapping.skill_section }}
|
||||
|
||||
{{ mapping.explanation }}
|
||||
|
||||
{% endfor %}
|
||||
|
||||
---
|
||||
|
||||
## Additional Context
|
||||
|
||||
**Why These Insights Were Selected**:
|
||||
{{ selection_rationale }}
|
||||
|
||||
**Insights Not Included** (if any):
|
||||
{% if excluded_insights %}
|
||||
{% for excluded in excluded_insights %}
|
||||
- {{ excluded.title }}: {{ excluded.reason }}
|
||||
{% endfor %}
|
||||
{% else %}
|
||||
All relevant insights were included.
|
||||
{% endif %}
|
||||
|
||||
---
|
||||
|
||||
**Generated**: {{ generated_date }}
|
||||
**Last Updated**: {{ updated_date }}
|
||||
139
skills/insight-skill-generator/workflow/phase-1-discovery.md
Normal file
139
skills/insight-skill-generator/workflow/phase-1-discovery.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# Phase 1: Insight Discovery and Parsing
|
||||
|
||||
**Purpose**: Locate, read, deduplicate, and structure all insights from the project's lessons-learned directory.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Verify project structure
|
||||
- Ask user for project root directory (default: current working directory)
|
||||
- Check if `docs/lessons-learned/` exists
|
||||
- If not found, explain the expected structure and offer to search alternative locations
|
||||
- List all categories found (testing, configuration, hooks-and-events, etc.)
|
||||
|
||||
### 2. Scan and catalog insight files
|
||||
|
||||
**File Naming Convention**:
|
||||
Files MUST follow: `YYYY-MM-DD-descriptive-slug.md`
|
||||
- Date prefix for chronological sorting
|
||||
- Descriptive slug (3-5 words) summarizing the insight topic
|
||||
- Examples:
|
||||
- `2025-11-21-jwt-refresh-token-pattern.md`
|
||||
- `2025-11-20-vitest-mocking-best-practices.md`
|
||||
- `2025-11-19-react-testing-library-queries.md`
|
||||
|
||||
**Scanning**:
|
||||
- Use Glob tool to find all markdown files: `docs/lessons-learned/**/*.md`
|
||||
- For each file found, extract:
|
||||
- File path and category (from directory name)
|
||||
- Creation date (from filename prefix)
|
||||
- Descriptive title (from filename slug)
|
||||
- File size and line count
|
||||
- Build initial inventory report
|
||||
|
||||
### 3. Deduplicate insights (CRITICAL)
|
||||
|
||||
**Why**: The extraction hook may create duplicate entries within files.
|
||||
|
||||
**Deduplication Algorithm**:
|
||||
```python
|
||||
def deduplicate_insights(insights):
|
||||
seen_hashes = set()
|
||||
unique_insights = []
|
||||
|
||||
for insight in insights:
|
||||
# Create hash from normalized content
|
||||
content_hash = hash(normalize(insight.title + insight.content[:200]))
|
||||
|
||||
if content_hash not in seen_hashes:
|
||||
seen_hashes.add(content_hash)
|
||||
unique_insights.append(insight)
|
||||
else:
|
||||
log_duplicate(insight)
|
||||
|
||||
return unique_insights
|
||||
```
|
||||
|
||||
**Deduplication Checks**:
|
||||
- Exact title match → duplicate
|
||||
- First 200 chars content match → duplicate
|
||||
- Same code blocks in same order → duplicate
|
||||
- Report: "Found X insights, removed Y duplicates (Z unique)"
|
||||
|
||||
### 4. Parse individual insights
|
||||
- Read each file using Read tool
|
||||
- Extract session metadata (session ID, timestamp from file headers)
|
||||
- Split file content on `---` separator (insights are separated by horizontal rules)
|
||||
- For each insight section:
|
||||
- Extract title (first line, often wrapped in `**bold**`)
|
||||
- Extract body content (remaining markdown)
|
||||
- Identify code blocks
|
||||
- Extract actionable items (lines starting with `- [ ]` or numbered lists)
|
||||
- Note any warnings/cautions
|
||||
|
||||
### 5. Apply quality filters
|
||||
|
||||
**Filter out low-depth 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
|
||||
- Best practices with concrete examples
|
||||
|
||||
**Quality Score Calculation**:
|
||||
```
|
||||
score = 0
|
||||
if has_actionable_items: score += 3
|
||||
if has_code_examples: score += 2
|
||||
if has_numbered_steps: score += 2
|
||||
if word_count > 200: score += 1
|
||||
if has_warnings_or_notes: score += 1
|
||||
|
||||
# Minimum score for skill consideration: 4
|
||||
```
|
||||
|
||||
### 6. Build structured insight inventory
|
||||
```
|
||||
{
|
||||
id: unique_id,
|
||||
title: string,
|
||||
content: string,
|
||||
category: string,
|
||||
date: ISO_date,
|
||||
session_id: string,
|
||||
source_file: path,
|
||||
code_examples: [{ language, code }],
|
||||
action_items: [string],
|
||||
keywords: [string],
|
||||
quality_score: int,
|
||||
paragraph_count: int,
|
||||
line_count: int
|
||||
}
|
||||
```
|
||||
|
||||
### 7. Present discovery summary
|
||||
- Total insights found (before deduplication)
|
||||
- Duplicates removed
|
||||
- Low-quality insights filtered
|
||||
- **Final count**: Unique, quality insights
|
||||
- Category breakdown
|
||||
- Date range (earliest to latest)
|
||||
- Preview of top 5 insights by quality score
|
||||
|
||||
## Output
|
||||
|
||||
Deduplicated, quality-filtered inventory of insights with metadata and categorization.
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **No lessons-learned directory**: Ask if user wants to search elsewhere or exit
|
||||
- **Empty files**: Skip and report count of empty files
|
||||
- **Malformed markdown**: Log warning but continue parsing (best effort)
|
||||
- **Missing session metadata**: Use filename date as fallback
|
||||
- **High duplicate count**: Indicates extraction hook bug - warn user
|
||||
- **All insights filtered as low-quality**: Lower threshold or suggest manual curation
|
||||
- **Files without descriptive names**: Suggest renaming for better organization
|
||||
@@ -0,0 +1,82 @@
|
||||
# Phase 2: Smart Clustering
|
||||
|
||||
**Purpose**: Group related insights using similarity analysis to identify skill candidates.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Load clustering configuration
|
||||
- Read `data/clustering-config.yaml` for weights and thresholds
|
||||
- Similarity weights:
|
||||
- Same category: +0.3
|
||||
- Shared keyword: +0.1 per keyword
|
||||
- Temporal proximity (within 7 days): +0.05
|
||||
- Title similarity: +0.15
|
||||
- Content overlap: +0.2
|
||||
- Clustering threshold: 0.6 minimum to group
|
||||
- Standalone quality threshold: 0.8 for single-insight skills
|
||||
|
||||
### 2. Extract keywords from each insight
|
||||
- Normalize text (lowercase, remove punctuation)
|
||||
- Extract significant words from title (weight 2x)
|
||||
- Extract significant words from body (weight 1x)
|
||||
- Filter out common stop words
|
||||
- Apply category-specific keyword boosting
|
||||
- Build keyword vector for each insight
|
||||
|
||||
### 3. Calculate pairwise similarity scores
|
||||
For each pair of insights (i, j):
|
||||
- Base score = 0
|
||||
- If same category: +0.3
|
||||
- For each shared keyword: +0.1
|
||||
- If dates within 7 days: +0.05
|
||||
- Calculate title word overlap: shared_words / total_words * 0.15
|
||||
- Calculate content concept overlap: shared_concepts / total_concepts * 0.2
|
||||
- Final score = sum of all components
|
||||
|
||||
### 4. Build clusters
|
||||
- Start with highest similarity pairs
|
||||
- Group insights with similarity >= 0.6
|
||||
- Use connected components algorithm
|
||||
- Identify standalone insights (don't cluster with any others)
|
||||
- For standalone insights, check if quality score >= 0.8
|
||||
|
||||
### 5. Assess cluster characteristics
|
||||
For each cluster:
|
||||
- Count insights
|
||||
- Identify dominant category
|
||||
- Extract common keywords
|
||||
- Assess complexity (lines, code examples, etc.)
|
||||
- Recommend skill complexity (minimal/standard/complex)
|
||||
- Suggest skill pattern (phase-based/mode-based/validation)
|
||||
|
||||
### 6. Handle large clusters (>5 insights)
|
||||
- Attempt sub-clustering by:
|
||||
- Temporal splits (early vs. late insights)
|
||||
- Sub-topic splits (different keyword groups)
|
||||
- Complexity splits (simple vs. complex insights)
|
||||
- Ask user if they want to split or keep as comprehensive skill
|
||||
|
||||
### 7. Present clustering results interactively
|
||||
For each cluster, show:
|
||||
- Cluster ID and size
|
||||
- Suggested skill name (from keywords)
|
||||
- Dominant category
|
||||
- Insight titles in cluster
|
||||
- Similarity scores
|
||||
- Recommended complexity
|
||||
|
||||
Ask user to:
|
||||
- Review proposed clusters
|
||||
- Accept/reject/modify groupings
|
||||
- Combine or split clusters
|
||||
- Remove low-value insights
|
||||
|
||||
## Output
|
||||
|
||||
Validated clusters of insights, each representing a skill candidate.
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **All insights are unrelated** (no clusters): Offer to generate standalone skills or exit
|
||||
- **One giant cluster**: Suggest sub-clustering or mode-based skill
|
||||
- **Too many standalone insights**: Suggest raising similarity threshold or manual grouping
|
||||
82
skills/insight-skill-generator/workflow/phase-3-design.md
Normal file
82
skills/insight-skill-generator/workflow/phase-3-design.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# Phase 3: Interactive Skill Design
|
||||
|
||||
**Purpose**: For each skill candidate, design the skill structure with user customization.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Propose skill name
|
||||
- Extract top keywords from cluster
|
||||
- Apply naming heuristics:
|
||||
- Max 40 characters
|
||||
- Kebab-case
|
||||
- Remove filler words ("insight", "lesson", "the")
|
||||
- Add preferred suffix ("guide", "advisor", "helper")
|
||||
- Example: "hook-deduplication-session-management" → "hook-deduplication-guide"
|
||||
- Present to user with alternatives
|
||||
- Allow user to customize
|
||||
|
||||
### 2. Generate description
|
||||
- Use action verbs: "Use PROACTIVELY when", "Guides", "Analyzes"
|
||||
- Include trigger context (what scenario)
|
||||
- Include benefit (what outcome)
|
||||
- Keep under 150 chars (soft limit, hard limit 1024)
|
||||
- Present to user and allow editing
|
||||
|
||||
### 3. Assess complexity
|
||||
Calculate based on:
|
||||
- Number of insights (1 = minimal, 2-4 = standard, 5+ = complex)
|
||||
- Total content length
|
||||
- Presence of code examples
|
||||
- Actionable items count
|
||||
|
||||
Recommend: minimal, standard, or complex
|
||||
- Minimal: SKILL.md + README.md + plugin.json + CHANGELOG.md
|
||||
- Standard: + data/insights-reference.md + examples/
|
||||
- Complex: + templates/ + multiple examples/
|
||||
|
||||
### 4. Select skill pattern
|
||||
Analyze insight content for pattern indicators:
|
||||
- **Phase-based**: sequential steps, "first/then/finally"
|
||||
- **Mode-based**: multiple approaches, "alternatively", "option"
|
||||
- **Validation**: checking/auditing language, "ensure", "verify"
|
||||
- **Data-processing**: parsing/transformation language
|
||||
|
||||
Recommend pattern with confidence level and explain trade-offs.
|
||||
|
||||
### 5. Map insights to skill structure
|
||||
For each insight, identify content types:
|
||||
- Problem description → Overview section
|
||||
- Solution explanation → Workflow/Phases
|
||||
- Code examples → examples/ directory
|
||||
- Best practices → Important Reminders
|
||||
- Checklists → templates/checklist.md
|
||||
- Trade-offs → Decision Guide section
|
||||
- Warnings → Important Reminders (high priority)
|
||||
|
||||
### 6. Define workflow phases (if phase-based)
|
||||
For each phase:
|
||||
- Generate phase name from insight content
|
||||
- Extract purpose statement
|
||||
- List steps (from insight action items or narrative)
|
||||
- Define expected output
|
||||
- Note common issues (from warnings in insights)
|
||||
|
||||
### 7. Preview the skill design
|
||||
Show complete outline:
|
||||
- Name, description, complexity
|
||||
- Pattern and structure
|
||||
- Section breakdown
|
||||
- File structure
|
||||
|
||||
Ask for final confirmation or modifications.
|
||||
|
||||
## Output
|
||||
|
||||
Approved skill design specification ready for generation.
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **User unsure about pattern**: Show examples from existing skills, offer recommendation
|
||||
- **Naming conflicts**: Check ~/.claude/skills/ and .claude/skills/ for existing skills
|
||||
- **Description too long**: Auto-trim and ask user to review
|
||||
- **Unclear structure**: Fall back to default phase-based pattern
|
||||
@@ -0,0 +1,89 @@
|
||||
# Phase 4: Skill Generation
|
||||
|
||||
**Purpose**: Create all skill files following the approved design.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Prepare generation workspace
|
||||
- Create temporary directory for skill assembly
|
||||
- Load templates from `templates/` directory
|
||||
|
||||
### 2. Generate SKILL.md
|
||||
- Create frontmatter with name and description
|
||||
- Add h1 heading
|
||||
- Generate Overview section (what, based on X insights, capabilities)
|
||||
- Generate "When to Use" section (trigger phrases, use cases, anti-use cases)
|
||||
- Generate Response Style section
|
||||
- Generate workflow sections based on pattern:
|
||||
- Phase-based: Phase 1, Phase 2, etc. with Purpose, Steps, Output, Common Issues
|
||||
- Mode-based: Mode 1, Mode 2, etc. with When to use, Steps, Output
|
||||
- Validation: Analysis → Detection → Recommendations
|
||||
- Generate Reference Materials section
|
||||
- Generate Important Reminders
|
||||
- Generate Best Practices
|
||||
- Generate Troubleshooting
|
||||
- Add Metadata section with source insight attribution
|
||||
|
||||
### 3. Generate README.md
|
||||
- Brief overview (1-2 sentences)
|
||||
- Installation instructions (standard)
|
||||
- Quick start example
|
||||
- Trigger phrases list
|
||||
- Link to SKILL.md for details
|
||||
|
||||
### 4. Generate plugin.json
|
||||
```json
|
||||
{
|
||||
"name": "[skill-name]",
|
||||
"version": "0.1.0",
|
||||
"description": "[description]",
|
||||
"type": "skill",
|
||||
"author": "Connor",
|
||||
"category": "[category from clustering-config]",
|
||||
"tags": ["insights", "lessons-learned", "[domain]"]
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Generate CHANGELOG.md
|
||||
Initialize with v0.1.0 and list key features.
|
||||
|
||||
### 6. Generate data/insights-reference.md (if complexity >= standard)
|
||||
- Add overview (insight count, date range, categories)
|
||||
- For each insight: title, metadata, original content, code examples, related insights
|
||||
- Add clustering analysis section
|
||||
- Add insight-to-skill mapping explanation
|
||||
|
||||
### 7. Generate examples/ (if needed)
|
||||
- Extract and organize code blocks by language or topic
|
||||
- Add explanatory context
|
||||
- Create usage examples showing example prompts and expected behaviors
|
||||
|
||||
### 8. Generate templates/ (if needed)
|
||||
- Create templates/checklist.md from actionable items
|
||||
- Organize items by section
|
||||
- Add verification steps
|
||||
- Include common mistakes section
|
||||
|
||||
### 9. Validate all generated files
|
||||
- Check YAML frontmatter syntax
|
||||
- Validate JSON syntax
|
||||
- Check file references are valid
|
||||
- Verify no broken markdown links
|
||||
- Run quality checklist
|
||||
- Report validation results to user
|
||||
|
||||
### 10. Preview generated skill
|
||||
- Show file tree
|
||||
- Show key sections from SKILL.md
|
||||
- Show README.md preview
|
||||
- Highlight any validation warnings
|
||||
|
||||
## Output
|
||||
|
||||
Complete, validated skill in temporary workspace, ready for installation.
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **Validation failures**: Fix automatically if possible, otherwise ask user
|
||||
- **Missing code examples**: Offer to generate placeholder or skip examples/ directory
|
||||
- **Large SKILL.md** (>500 lines): Suggest splitting content into separate files
|
||||
@@ -0,0 +1,88 @@
|
||||
# Phase 5: Installation and Testing
|
||||
|
||||
**Purpose**: Install the skill and provide testing guidance.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Ask installation location
|
||||
Present options:
|
||||
- **Project-specific**: `[project]/.claude/skills/[skill-name]/`
|
||||
- Pros: Version controlled with project, only available in this project
|
||||
- Cons: Not available in other projects
|
||||
- **Global**: `~/.claude/skills/[skill-name]/`
|
||||
- Pros: Available in all projects
|
||||
- Cons: Not version controlled (unless user manages ~/.claude with git)
|
||||
|
||||
### 2. Check for conflicts
|
||||
- Verify chosen location doesn't already have a skill with same name
|
||||
- If conflict found:
|
||||
- Show existing skill details
|
||||
- Offer options: Choose different name, Overwrite (with confirmation), Cancel
|
||||
|
||||
### 3. Copy skill files
|
||||
- Create target directory
|
||||
- Copy all generated files preserving structure
|
||||
- Set appropriate permissions
|
||||
- Verify all files copied successfully
|
||||
|
||||
### 4. Re-validate installed skill
|
||||
- Read SKILL.md from install location
|
||||
- Verify frontmatter is still valid
|
||||
- Check file references work from install location
|
||||
- Confirm no corruption during copy
|
||||
|
||||
### 5. Test skill loading
|
||||
- Attempt to trigger skill using one of the trigger phrases
|
||||
- Verify Claude Code recognizes the skill
|
||||
- Check skill appears in available skills list
|
||||
- Report results to user
|
||||
|
||||
### 6. Provide testing guidance
|
||||
Show trigger phrases to test:
|
||||
```
|
||||
Try these phrases to test your new skill:
|
||||
- "[trigger phrase 1]"
|
||||
- "[trigger phrase 2]"
|
||||
- "[trigger phrase 3]"
|
||||
```
|
||||
|
||||
Suggest test scenarios based on skill purpose and explain expected behavior.
|
||||
|
||||
### 7. Offer refinement suggestions
|
||||
Based on skill characteristics, suggest potential improvements:
|
||||
- Add more examples if skill is complex
|
||||
- Refine trigger phrases if they're too broad/narrow
|
||||
- Split into multiple skills if scope is too large
|
||||
- Add troubleshooting section if skill has edge cases
|
||||
|
||||
Ask if user wants to iterate on the skill.
|
||||
|
||||
### 8. Document the skill
|
||||
Offer to add skill to project documentation:
|
||||
```markdown
|
||||
### [Skill Name]
|
||||
**Location**: [path]
|
||||
**Purpose**: [description]
|
||||
**Trigger**: "[main trigger phrase]"
|
||||
**Source**: Generated from [X] insights ([categories])
|
||||
```
|
||||
|
||||
### 9. Next steps
|
||||
Suggest:
|
||||
- Test the skill with real scenarios
|
||||
- Share with team if relevant
|
||||
- Iterate based on usage (version 0.2.0)
|
||||
- Generate more skills from other insight clusters
|
||||
|
||||
Ask if user wants to generate another skill from remaining insights.
|
||||
|
||||
## Output
|
||||
|
||||
Installed, validated skill with testing guidance and refinement suggestions.
|
||||
|
||||
## Common Issues
|
||||
|
||||
- **Installation permission errors**: Check directory permissions, suggest sudo if needed
|
||||
- **Skill not recognized**: Verify frontmatter format, check Claude Code skill discovery
|
||||
- **Trigger phrases don't work**: Suggest broadening or clarifying phrases
|
||||
- **Conflicts with existing skills**: Help user choose unique name or merge functionality
|
||||
Reference in New Issue
Block a user