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: 
Mode: 

Summary:
- 
- 
- 

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Chevis-Zhou
• Source: Chevis-Zhou/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.