Feature Sparks Plugin

Use Cases

1. Capture Hard-Won Debugging Knowledge

After spending time debugging a tricky issue:

/learn the JWT refresh token was failing because...

Creates a gotcha that loads automatically when someone hits similar symptoms.

2. Document Feature Architecture

After implementing or understanding a feature:

/learn how the auth system works

Creates a feature dossier with flows, key files, and common tasks.

3. Record Architectural Decisions

After making a significant choice:

/learn we chose Redis over Postgres for sessions because...

Preserves the rationale so future you (or teammates) don't reverse it blindly.

4. Find Existing Knowledge

Before diving into unfamiliar code:

/find auth

Searches registry, loads relevant skills into context before you start.

User Flows

Capture Knowledge (/learn)

1. User invokes /learn with optional topic
2. Learn skill analyzes conversation for capture-worthy knowledge
3. Proposes learning with category, triggers, description
4. On approval: creates skill file + registers in registry + regenerates find skill
5. Confirmation shown to user

Find Knowledge (/find or sparks-find skill)

1. User invokes /find {query} or Claude loads sparks-find skill
2. Registry embedded in skill - no extra file reads
3. Single match → auto-loads skill into context
4. Multiple matches → asks user which to load
5. Knowledge available for current task

Auto-Apply (SessionStart Hook)

1. Session starts in project with sparks
2. Hook reads registry, counts entries
3. Injects compliance instructions + registry into context
4. Claude checks registry before searching codebase
5. Matching skills loaded via Skill({skill-name})

Technical Design

Storage Structure (Project-Level)

{{project}}/.claude/skills/
├── sparks-find/
│   ├── SKILL.md                      # Find skill (generated, embedded registry)
│   └── references/
│       └── registry.toon             # Registry source of truth
├── {category}-{slug}/                # Each learning = one skill
│   └── SKILL.md
└── ...

Plugin Structure

plugins/sparks/
├── skills/
│   ├── learn/
│   │   ├── SKILL.md                  # Capture workflow
│   │   └── references/
│   │       └── find-template.md      # Template for project find skill
│   └── apply/
│       └── SKILL.md                  # Compliance (fallback for non-hook agents)
└── hooks/scripts/
    ├── load-knowledge.py             # SessionStart - injects registry
    └── register_spark.py             # Creates registry + find skill

Registry Format

# registry.toon
{skill-name}|{category}|{triggers}|{description}

Example:

feature-auth-flows|feature|auth, login, JWT|Use when implementing or debugging authentication
gotchas-hook-timeout|gotchas|hook, timeout, silent|Use when hooks fail without error output

Categories

Key Architecture Decisions

1. Project-scoped find skill - generated per-project with embedded registry, not plugin-level
2. Per-skill storage - each learning is a separate skill file, not inline in registry
3. user-invocable: false - skills don't clutter /skill list but agent loads via Skill tool
4. Apply skill retained - fallback compliance for agents without SessionStart hooks
5. Registry regenerates find skill - register_spark.py keeps find skill in sync

Key Files

Common Tasks

Adding a New Category

1. Update category table in plugins/sparks/skills/learn/SKILL.md
2. Add to apply skill categories list
3. Document when to use it with clear examples

Debugging Hook Issues

1. Verify registry exists at .claude/skills/sparks-find/references/registry.toon
2. Test hook output: cd /project && python3 plugins/sparks/hooks/scripts/load-knowledge.py
3. Check for valid JSON output with systemMessage and additionalContext

Testing Learn Flow

1. Run /learn in project with a topic
2. Verify skill created at .claude/skills/{category}-{slug}/SKILL.md
3. Verify registry updated at .claude/skills/sparks-find/references/registry.toon
4. Verify find skill regenerated with new entry embedded