FrancoStino/compile-knowledge

Compile Knowledge

Overview

Durable knowledge is worth keeping as many small, interlinked markdown files compiled over time and surfaced through an index — not as one giant doc, a chat log, or a one-off notes.md that rots. This skill makes compiling consistent, so what an agent learns in one session is retrievable in the next one instead of being re-derived from scratch.

The shape is deliberately boring: one fact per file, a one-line description that recall matches against, [[slug]] links between related files, and a single index line per entry. The hard part is not the format — it is the discipline of writing only what is durable, and of updating an existing file instead of creating a near-duplicate.

When to Use This Skill

• Use when you have just produced research, competitive intel, a digest, or an investigation result, and are about to close the task — compile before you close.
• Use when you learn a non-obvious fact the hard way (a tool that fails silently, a measurement that contradicts the docs, a constraint nobody wrote down).
• Use when the user says "save this", "write this to the wiki", "update the memory", "log this finding", "structure this knowledge", or "follow the karpathy method".
• Do not use it for routine work. A deploy, a restart, or a one-line fix usually produces nothing durable, and filler pollutes recall.

How It Works

Step 1: Pick the store

• Agent memory — the per-agent folder your harness already loads (memory/ with an index file such as MEMORY.md). This is the default and, for a solo agent, usually the only store you need.
• Shared wiki — a wiki/ folder with wiki/index.md, for knowledge the whole team would otherwise re-derive. Skip it entirely if you work alone; do not manufacture team ceremony.

Rule of thumb: "only I act on this" goes to memory, "anyone on my team might need this" goes to the wiki. Cross-link the two with [[slug]] rather than copying the fact into both.

Step 2: Pass the hygiene gate

Compile only a fact that is durable and non-obvious. Skip it if it is derivable from the repository, the git history, or the existing docs; if it is true only for this one conversation; or if an existing file already covers it — in that last case update that file.

Step 3: Search before you write

Grep the store and skim the index for the topic. A near-duplicate is worse than no entry, because recall then has two answers and no way to choose between them.

Step 4: Write one atomic file

One fact per file. Two unrelated facts are two files. Name it as a kebab-case slug — the slug is the link target, so it has to be guessable by the next reader. Frontmatter carries name (equal to the slug), a one-line description specific enough to be matched during recall, and a type or category. In the body, state the fact plainly and link related entries with [[slug]] liberally; a link to a file that does not exist yet is a fine TODO marker, not an error.

Step 5: Add exactly one index line

Use one line in the form - Title → slug.md — hook, under ~200 characters. Detail lives in the file; an index line that restates the file defeats the point of having an index. Create the index if it is missing, or the store is undiscoverable.

Step 6: Age the fact instead of letting it rot

Facts expire. When one is time-sensitive or replaces an older one, say so in the frontmatter so recall can demote it rather than serving stale truth:

• valid_to: YYYY-MM-DD — the date the fact needs a recheck.
• supersedes: <slug> — the older fact this replaces. Prefer this over editing in place when the old value is still worth seeing; edit in place when it is not.
• confidence: high|medium|low — so a hunch never outranks a measurement.
• provenance: "<source>" — where the fact came from, distinct from who wrote the note.

All four are optional and portable; omitting them changes nothing.

Examples

Example 1: A measured, non-obvious fact goes to memory

---
name: reference_search_api_counts_prs_as_issues
description: "GitHub's /search/issues endpoint counts pull requests in total_count, so a zero there proves neither issues nor PRs exist — but a non-zero one does not tell you which."
confidence: high
provenance: "measured 2026-08-16 while dupe-checking four upstream repos"
---

`total_count` from `/search/issues?q=<term>+repo:<owner>/<name>` is the sum of issues and
pull requests. For a "has anyone submitted this yet?" check that is exactly what you want,
and the zero is a real absence. To separate the two, add `type:pr` or `type:issue`.

Related: [[reference_gh_api_ref_serves_default_branch]].

Then one line in the index:

- Search API counts PRs as issues → reference_search_api_counts_prs_as_issues.md — a zero is a real absence, a non-zero is ambiguous

Example 2: Nothing durable came out of the task

Task: bump the service's log level to debug and restart it.

Compile? No. It is derivable from the config file and the deploy history, and it is true
only for today. Close the task without writing anything.

Best Practices

• ✅ Search the store before writing; update the existing file when one exists.
• ✅ Keep one fact per file and one line per file in the index.
• ✅ Write the description for the person searching later, in their vocabulary, not yours.
• ✅ Convert relative dates ("yesterday", "last release") to absolute ones at write time.
• ✅ Delete entries that turn out to be wrong — a wrong memory is worse than a missing one.
• ❌ Don't compile something the repository, its history, or its docs already say.
• ❌ Don't leave research as a standalone notes.md and call it compiled.
• ❌ Don't duplicate the same fact into both memory and the wiki; pick one home, cross-link.
• ❌ Don't write filler to satisfy a checklist.

Limitations

• This skill organizes knowledge; it does not verify it. A confidently written wrong fact becomes a confidently retrieved wrong fact, so record how you measured something, not only what you concluded.
• Retrieval quality is bounded by the description line. A vague description makes a good entry unfindable.
• It does not replace environment-specific validation, testing, or expert review.
• Stop and ask for clarification if the store's location or its index file is ambiguous.

Security & Safety Notes

• This skill writes, edits, and occasionally deletes markdown files. Confine every one of those operations to the knowledge store directory (the agent's memory/ folder or the project's wiki/), and never to source files, configuration, or anything outside it.
• Deleting a superseded entry is destructive and unreviewable after the fact. Prefer supersedes: when the old value still has audit value, and confirm before removing a file you did not write.
• Never compile a secret, credential, token, or personal identifier into a knowledge store. These files are long-lived, frequently synced, and often shared across a team — treat them as if they were public. Record the shape of a credential, never its value.
• The skill runs no shell commands and makes no network fetches of its own.

Common Pitfalls

• Problem: The index grows into a second copy of the store. Solution: Cap each entry at one line and let the file carry the detail; when the index gets long, tighten the hooks rather than adding more of them.
• Problem: Two files describe the same fact slightly differently, so recall returns both and the reader trusts neither. Solution: Merge them into the older slug and leave the newer one deleted; the search in Step 3 exists to prevent this.
• Problem: A fact was true when written and is quietly false now. Solution: Stamp valid_to: on anything time-sensitive at write time, and verify a recalled fact that names a file, flag, or endpoint before acting on it.
• Problem: Nothing ever gets compiled because it always feels like the wrong moment. Solution: Bind it to a boundary you already hit — compile before closing a task, not as a separate chore you schedule later.

Related Skills

• @writing-skills - When you want to package a repeatable procedure as a skill rather than record a fact.
• @deep-research - Produces the findings; this skill is what keeps them after the session ends.