Initial commit

skills/insight-skill-generator/data/clustering-config.yaml

@@ -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"

skills/insight-skill-generator/data/quality-checklist.md

@@ -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

skills/insight-skill-generator/data/skill-templates-map.yaml

@@ -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"