insight-crystallizer
Skill6 starsChanged 29 days agoMITView on GitHub
Capture valuable insights, analyses, and decisions from a chat session and file them as persistent markdown so they survive past the current context. Use when a conversation produces something worth keeping — a comparison, a decision with rationale, a research synthesis, a non-obvious debugging finding, a framework. Triggers — "file this", "save this insight", "this is worth keeping", "remember this analysis", "crystallize this", "don't lose this". Also trigger proactively after deep analytical work whose result would help future sessions. Prevents the "forgotten session" problem where valuable thinking evaporates when the chat ends.
In this repository30 other files it gives its agents.
- adversarial-re-readSkill
- adversarial-reviewSkill
- build-estimateSkill
- build-evaluateSkill
- build-executeSkill
- build-planSkill
- build-polishSkill
- build-prdSkill
- build-probeSkill
- build-validateSkill
- excel-connector-governanceSkill
- five-whysSkill
- insight-builderSkill
- insight-promotionSkill
- multi-sessionSkill
- notion-governanceSkill
- oodaSkill
- prd-writerSkill
- promote-to-toolingSkill
- quality-reviewSkill
- ralph-implementSkill
- ralph-loopSkill
- search-governanceSkill
- session-outputSkill
- skill-validatorSkill
- task-planSkill
- verifySkill
- voice-profile-testSkill
- why-diagnosticSkill
- writing-qualitySkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 6 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 45
Read the conversation. Identify what is worth preserving.
- Very specific: line 95
Default location: docs/insights/YYYY-MM-DD-<slug>.md.
- Distinctive: line 136
After filing, check whether the new insight connects to or updates existing knowledge.
- Very specific: line 140
Search docs/insights/ for related entries.
- Distinctive: line 148
If 3+ insights now exist on the same topic, mention it: "You have N insights on [topic].
- Very specific: line 152
Default location: docs/insights/.
- Distinctive: line 157
If the directory does not exist, the skill creates it on first write.
- Very specific: line 161
If the insight meets any of these criteria, suggest promoting it via the insight-promotion skill before closing the task:
- Distinctive: line 202
Only recommend this chain when the insight came from a failure or a fix.
- Very specific: line 208
If a script or gate could enforce it instead, recommend insight-builder first.
- Distinctive: line 209
Nothing to change: stop. Say "Filed, no further step" and why.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Insight Crystallizer
Most chat sessions produce throwaway exchanges — quick questions, formatting, routine tasks. Some produce real intellectual work: a comparison that weighed three options, a debugging session that uncovered a non-obvious root cause, a framework that connected strategy to implementation.
That work dies when the chat ends unless it gets crystallized.
The core idea
Adapted from Karpathy's "file good answers back" pattern: when an answer is valuable, it shouldn't disappear into chat history. It becomes a first-class record — searchable, linkable, available to future sessions.
This skill files insights as markdown under docs/insights/ by default. The path is configurable per project — see Configuration.
When to crystallize
Suggest proactively after any of these
- A comparison or evaluation of tools, approaches, or vendors
- A synthesis that connected dots across multiple files, modules, or projects
- A decision with explicit trade-offs and rationale
- A research summary on a topic relevant to active work
- A technical architecture or design decision
- A debugging session that uncovered a non-obvious root cause
- A competitive intelligence finding or market analysis
- An analysis that required 3+ tool calls, web searches, or file reads to assemble
Manual triggers
The user explicitly asks to save, file, log, remember, or crystallize the insight.
Skip if
- Routine Q&A (definitions, syntax, formatting)
- Work already filed elsewhere (commits, tickets, docs)
- Draft content that has not been reviewed
- Opinions or preferences without analytical backing
- Anything the user said to discard
Phase 1 — Extract
Read the conversation. Identify what is worth preserving. Not everything from a productive session needs to be kept — extract the signal, not the process.
Structure the extraction as:
Title
A clear, searchable title in the format: [Type] Topic — Key Finding.
Examples:
Analysis: SQLite vs Postgres for local-first sync — Postgres wins under N concurrent writersDecision: Use server components by default — rationale documentedFinding: Race condition in queue draining when worker exits during retryComparison: Vector store options — short benchmark table, hybrid recommended
Insight Type
Classify so retrieval is easier later:
- Analysis — evaluation of options with trade-offs and a recommendation
- Research — synthesized findings from multiple sources
- Decision — a choice made with documented rationale
- Finding — a non-obvious discovery (bug, pattern, gotcha)
- Framework — a reusable mental model or decision template
- Comparison — structured evaluation of alternatives
- Strategy — directional thinking about approach or positioning
Summary (2-4 sentences)
The key takeaway. If a reader only reads this, they should know what was decided or discovered and why it matters.
Full Content
The detailed analysis, comparison table, decision rationale, or research findings. Include the question, sources consulted, reasoning, conclusion, and any caveats or open questions.
Connections
Which other files, modules, decisions, or insights does this relate to? Capture as a short list of relative paths or insight slugs.
Confidence and Shelf Life
- Confidence: High (well-sourced and verified) / Medium (reasonable but not verified) / Low (preliminary)
- Shelf life: Evergreen / Seasonal / Perishable. Perishable insights include a re-check-by date.
Phase 2 — Confirm before writing
Present the extracted insight for review. Wait for confirmation. Common adjustments: wrong scope, confidence adjustment, additional context, don't file after all.
Phase 3 — Write the markdown file
Default location: docs/insights/YYYY-MM-DD-<slug>.md. The slug is a kebab-case short title (3-5 words). Example: 2026-05-10-postgres-vs-sqlite-local-first.md.
File template
---
title: [The full title]
type: [analysis | research | decision | finding | framework | comparison | strategy]
date: YYYY-MM-DD
confidence: [high | medium | low]
shelf_life: [evergreen | seasonal | perishable]
recheck_by: [YYYY-MM-DD or omit]
connections:
- [relative path or slug]
---
# [Title]
## Summary
[The 2-4 sentence summary.]
## Context
[The question or problem that prompted the work.]
## Analysis
[The full content — sources consulted, reasoning, findings, conclusion.]
## Open Questions
[Anything unresolved. Omit if nothing is open.]
## Sources
[Sources, URLs, files, or tools consulted. Be specific — paths, line numbers, commit hashes, URL plus retrieval date.]Phase 4 — Optional follow-up
After filing, check whether the new insight connects to or updates existing knowledge.
Connection check
Search docs/insights/ for related entries. If the new insight:
- Supersedes an older one — add
superseded_by:to the old frontmatter; do not delete it. - Contradicts an older one — flag for the user: "This contradicts [old slug]. Update or keep both?"
- Extends an older one — add cross-references in both frontmatters.
Pattern detection
If 3+ insights now exist on the same topic, mention it: "You have N insights on [topic]. Want me to synthesize them into a consolidated overview?"
Configuration
Default location: docs/insights/. Override per project by:
- Setting
INSIGHTS_DIR=pathin the environment, OR - Adding
.claude/rules/insights-location.mdwith one line:Insights directory: <path>.
If the directory does not exist, the skill creates it on first write.
When to escalate
If the insight meets any of these criteria, suggest promoting it via the insight-promotion skill before closing the task:
- Pattern recurrence — describes a failure or decision that has come up twice or more.
- Governance gap — reveals that existing rules are silent on a real scenario.
- Failure prevention — documents a specific, reproducible failure mode with a known fix.
- Cross-session applicability — relevant to future sessions that will not mention the originating context.
docs/insights/ is where knowledge lives. .claude/rules/ and CLAUDE.md are where knowledge is enforced.
Agent integration
evidence-auditor— if the insight cites external sources (URLs, papers, claims attributed to third parties), runs before filing. Confirms each citation traces accurately. An insight with fabricated citations is worse than no insight.research-analyst— if the insight synthesizes across 3+ external sources, invoke before drafting the Analysis section. Produces the cited-claims table the insight depends on.knowledge-synthesizer— invoked when Phase 4 detects 3+ related insights indocs/insights/. Combines them into a consolidated overview so individual insights compound into knowledge rather than a pile.
<!-- INSIGHT-CHAIN v1 -->The insight chain
Type "insight" to find the trio. Each step ends by recommending the next one.
| # | Skill | Required? | What it gives you |
| 1 | five-whys or why-diagnostic | Optional | The cause, or an honest "cause not established" |
| 2 | insight-crystallizer | Always | The lesson, filed so it outlives the chat |
| 3 | insight-builder | Optional | A built fix, tested twice, proven shipped |
| 4 | insight-promotion | Optional | The lesson made always-on, pointing at the fix |
You are here: step 2. Fix before promote: a rule written before its fix is proven tells every future session to follow a guess.
Next step (end every run with this)
Finish with this block, filled in. Short, plain, numbered.
Next step
1. <one action, who does it> (recommended)
2. <alternative, if any>
Why: <one sentence>Only recommend this chain when the insight came from a failure or a fix. For other insights (a comparison, a strategy), stop after filing.
- Something must be built or changed (a script, hook, gate, config, prompt, plugin or
skill): recommend
insight-builder. - The only change is a rule future sessions must follow: recommend
insight-promotion. If a script or gate could enforce it instead, recommendinsight-builderfirst. - Nothing to change: stop. Say "Filed, no further step" and why.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

