# Insight Crystallizer > 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. - Skill: `shawnclybor/insight-crystallizer` (Agent Skill) - Install (CLI): `npx skillmds@latest add shawnclybor/insight-crystallizer` - Raw SKILL.md: https://api.skillmd.com/api/skills/shawnclybor/insight-crystallizer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: shawnclybor (https://skillmd.com/u/shawnclybor) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/shawnclybor/insight-crystallizer --- # 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 writers` - `Decision: Use server components by default — rationale documented` - `Finding: Race condition in queue draining when worker exits during retry` - `Comparison: 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-.md`. The slug is a kebab-case short title (3-5 words). Example: `2026-05-10-postgres-vs-sqlite-local-first.md`. ### File template ```markdown --- 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=path` in the environment, OR - Adding `.claude/rules/insights-location.md` with one line: `Insights directory: `. 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: 1. **Pattern recurrence** — describes a failure or decision that has come up twice or more. 2. **Governance gap** — reveals that existing rules are silent on a real scenario. 3. **Failure prevention** — documents a specific, reproducible failure mode with a known fix. 4. **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 in `docs/insights/`. Combines them into a consolidated overview so individual insights compound into knowledge rather than a pile.