Thread to kb

Thread-to-KB

Purpose

doc-merge handles the heavy case: two documents on the table, full reconciliation, voice preservation, structural rework. This skill handles the light, frequent case: the source is the conversation we just had, and the target is a knowledge base file already in the current context (Project knowledge, Cowork folder, or a .md in a Claude Code repo). Output is a tight, append-or-weave update — not a rewrite.

When to use

• A discussion in the current thread produced a new decision, fact, pattern, fix, or refined opinion that should outlive the chat.
• A target KB file already exists in context and the user wants the new knowledge folded in.
• the user says any of the trigger phrases in the description, OR the situation clearly calls for "save what we just figured out."

When NOT to use

• Two separate documents need merging → use doc-merge.
• Raw unstructured notes with no target file → use messy-notes-organizer.
• Building a brand-new KB from zero → just write it directly, no skill needed.
• The "discussion" is one message long with no real synthesis → just answer normally.

Workflow

Step 1 — Identify the target file

Confirm the target KB file before doing anything else. Order of preference:

1. the user named it explicitly ("update framercode.md") → use that.
2. Exactly one obvious KB file in the project/folder/repo context → use that, state it in one line: "Updating framercode/SKILL.md."
3. Multiple plausible targets, or none visible → stop and ask which file. Do not guess. (the user's ambiguity protocol applies.)

Step 2 — Distill the thread

Re-read the current conversation and extract only what is new, decided, or worth preserving. Apply this filter:

• ✅ Decisions reached, with the reasoning that survived scrutiny
• ✅ Facts verified (not just claimed) during the chat
• ✅ Patterns, snippets, configs, or fixes that worked
• ✅ Corrections to prior assumptions in the existing KB
• ❌ Dead ends that were abandoned
• ❌ Restating what the KB already says
• ❌ Conversational scaffolding ("good question", "let me think")
• ❌ Tentative musings that never landed

Target length: as short as the knowledge demands. A two-line addition is a valid output. Resist padding.

Step 3 — Decide integration mode

Pick one based on the relationship between the new content and the existing file. State the choice in one line before producing output.

Mode	When to use	What it looks like
Append	New knowledge is additive and doesn't touch existing sections	Add to the bottom or to the relevant section's end
Weave	New knowledge refines or clarifies existing content	Edit in place, preserving surrounding voice and structure
Correct	New knowledge contradicts something in the existing file	Replace the wrong passage; flag the change explicitly in the response

Never silently overwrite. If anything is being removed or contradicted, call it out in the response summary.

Step 4 — Match the existing file's voice and structure

Before writing, scan the target file for:

• Heading style (## vs ###, sentence case vs Title Case)
• Bullet vs prose preference
• Code fence language tags
• First-person vs imperative voice
• Any existing section the new content naturally belongs under

Match it. The update should read like the same author wrote it.

Step 5 — Produce the edit

Three delivery formats depending on context:

• Claude Project / Cowork: output the full updated section(s) in a code block, clearly marked with the target filename and which section is changing. the user will paste it back.
• Claude Code repo (.md file accessible via filesystem): use str_replace or direct file edit on the actual file. Show a brief diff-style summary in the response.
• Google Drive / external doc (target is a Google Doc, Notion page, or any destination outside Claude's filesystem): output the patch as raw markdown text with no code fence wrapper. This lets the user select-all and paste directly without stripping backtick fences. Use a horizontal rule (---) as the section divider if multiple patches are produced.

If the user doesn't specify a target context and no KB file is visible in the project, ask whether the destination is Google Drive / external before producing output.

If the file isn't directly editable (Project knowledge), never pretend you edited it — produce the patch for manual application.

Step 6 — Summarize the change

End with a 2–4 line summary:

• What was added/changed/corrected
• Where it landed in the file
• Anything the user should double-check (especially for Correct mode)

No celebration, no "let me know if you need anything else." BLUF, then stop.

Output template

Target: <filename>
Mode: <append | weave | correct>

<the patch — full updated section, code block, or str_replace diff>

Summary:
- <change 1>
- <change 2>
- <flag if anything was contradicted/removed>

Anti-patterns

• Don't restate the thread. The KB doesn't need the conversation transcript, only the distilled knowledge.
• Don't pad to look thorough. A three-line update is a successful output if three lines is what the discussion produced.
• Don't invent structure. Match the file you're updating; don't impose new heading hierarchies.
• Don't merge tangents. If the thread covered three unrelated topics, ask which one to capture, or produce three clearly separated patches.
• Don't skip Step 1. Guessing the target file is the most common failure mode and the easiest to avoid.