agentleFS
shawnclyborshawnclybor/clybor-claude-tooling/.claude/skills/insight-crystallizer/SKILL.md

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.

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
  1. Distinctive:

    Read the conversation. Identify what is worth preserving.

    line 45
  2. Very specific:

    Default location: docs/insights/YYYY-MM-DD-<slug>.md.

    line 95
  3. Distinctive:

    After filing, check whether the new insight connects to or updates existing knowledge.

    line 136
  4. Very specific:

    Search docs/insights/ for related entries.

    line 140
  5. Distinctive:

    If 3+ insights now exist on the same topic, mention it: "You have N insights on [topic].

    line 148
  6. Very specific:

    Default location: docs/insights/.

    line 152
  7. Distinctive:

    If the directory does not exist, the skill creates it on first write.

    line 157
  8. Very specific:

    If the insight meets any of these criteria, suggest promoting it via the insight-promotion skill before closing the task:

    line 161
  9. Distinctive:

    Only recommend this chain when the insight came from a failure or a fix.

    line 202
  10. Very specific:

    If a script or gate could enforce it instead, recommend insight-builder first.

    line 208
  11. Distinctive:

    Nothing to change: stop. Say "Filed, no further step" and why.

    line 209

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-<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=path in the environment, OR
  • Adding .claude/rules/insights-location.md with 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:

  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.
<!-- INSIGHT-CHAIN v1 -->

The insight chain

Type "insight" to find the trio. Each step ends by recommending the next one.

#SkillRequired?What it gives you
1five-whys or why-diagnosticOptionalThe cause, or an honest "cause not established"
2insight-crystallizerAlwaysThe lesson, filed so it outlives the chat
3insight-builderOptionalA built fix, tested twice, proven shipped
4insight-promotionOptionalThe 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, recommend insight-builder first.
  • Nothing to change: stop. Say "Filed, no further step" and why.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.