# Wiki Handoff

> Capture or checkpoint a Claude session into a project wiki. Use when the user says "handoff", "wrap up", "snapshot", "save and continue", "capture this for next session", "write this to the wiki", or at meaningful checkpoints in a substantive session. Two modes — handoff (end-of-session writeup; commits and pushes if git is on) and snapshot (mid-session checkpoint that writes deltas and bridges to /compact). Discovers schema across wiki/CLAUDE.md, wiki/SCHEMA.md, ./CLAUDE.md, and ./WIKI.md; bootstraps from a bundled seed if none found. Git operations are optional — detected at runtime, skipped on non-repos.

- Skill: `sunfmin/wiki-handoff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sunfmin/wiki-handoff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sunfmin/wiki-handoff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sunfmin (https://skillmd.com/u/sunfmin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sunfmin/wiki-handoff

---


# Wiki Handoff

## Overview

Bidirectional ritual for the project wiki:

- Persist what was learned, decided, built, or deferred so a future session
  can pick up cold.
- Bridge mid-session checkpoints to `/compact` so the active window stays
  healthy without losing facts.

The wiki schema is project-specific. **Always discover and read the schema
file first** — it overrides every default in this skill.

## Modes

| Mode | When | What it does |
|---|---|---|
| `handoff` *(default)* | "handoff", "wrap this up", "capture this", "ingest this session", end of a substantive session | Full session digest: write/extend pages, update index, append log entry, then commit + push if git is on |
| `snapshot` | "snapshot", "save and continue", "checkpoint to wiki" — invoked mid-session | Minimal write of *new* facts since session start, plus a recommended `/compact <instruction>` string that names what's now safely persisted and what to drop from the active window |

Choose based on what the user said and on whether the session is ending or
continuing.

## Don't Use When

- Trivial sessions (one-line bugfix, formatting). The git log is enough.
- Information is already obvious from `git log` / `git blame` / the code
  itself. The wiki is for *non-derivable* knowledge.

## Pre-flight (always, both modes)

Run before any writes:

1. **Locate the schema.** See [Schema Discovery](#schema-discovery). If none
   found → [Initialize Wiki](#initialize-wiki-first-time-setup).
2. **Detect git.** `git rev-parse --is-inside-work-tree 2>/dev/null`.
   If false, set git=off — the workflow still writes files but skips
   commit / push / status steps. Tell the user once at the end.
3. **Read existing pages you plan to touch.** Extend, never overwrite. If
   new info contradicts old, flag it inline.
4. **Use the absolute YYYY-MM-DD** from the system context. Never write
   "today" or "yesterday".

## Schema Discovery

Search this order; first hit wins:

1. `wiki/CLAUDE.md`
2. `wiki/SCHEMA.md`
3. `./CLAUDE.md` — *only if* it contains the LLM Wiki pattern (mentions
   `index.md`, `log.md`, raw/wiki/schema layers, or "LLM Wiki")
4. `./WIKI.md`

If the schema specifies a directory layout, frontmatter shape, link
convention, or topic scope, **defer to it** over the defaults in this
skill. In particular:

- **Link style** — schema picks `[[wikilinks]]` vs `[text](path.md)`. Don't
  override.
- **Subdirectories** — if existing `wiki/` is flat, write flat. Don't
  `mkdir entities/concepts/sources/comparisons/` unless schema says so.
- **Page types** — use the schema's taxonomy; the default table below is
  fallback only.

## Initialize Wiki (first-time setup)

Trigger: schema discovery returned nothing **and** `wiki/` is either
absent or contains no markdown files.

If `wiki/` has files but no schema, **do not** bootstrap a parallel
layout. Instead, infer the existing shape (flat vs categorized, link
style, frontmatter) and write a schema file that matches before
proceeding.

Steps:

1. **Locate the bundled seed.** It lives at `seeds/llm-wiki.md` next to
   this `SKILL.md`. If you don't know the SKILL.md path, try in order:
   `~/.agents/skills/wiki-handoff/seeds/llm-wiki.md`,
   `~/Developments/wiki-handoff/seeds/llm-wiki.md`. Last resort: `find ~ -path '*wiki-handoff/seeds/llm-wiki.md' 2>/dev/null | head -1`.
   Do **not** fetch from the internet — the seed is bundled to be offline-safe.
2. **Copy it** to `wiki/CLAUDE.md`.
3. **Ask the user one question** before scaffolding directories:
   > Flat layout (`wiki/<topic>.md`) or categorized
   > (`wiki/{entities,concepts,sources,comparisons}/`)? Default: flat.
4. Create empty `wiki/index.md` with `# Index` heading and one section
   per category (matching the chosen layout).
5. Create empty `wiki/log.md` with `# Log` heading.
6. Create empty `raw/sources/` for source pointers.
7. If git is on, commit as a separate scope: `wiki: initialize from llm-wiki seed`.
8. Tell the user the wiki was initialized from the seed and point them at
   `wiki/CLAUDE.md` to adjust the schema before the next handoff. Then
   proceed with the requested mode.

## What to Capture — the Non-derivable Gate

Before writing each page or paragraph, **answer this**:

> Could a future session derive this from `git log`, the code,
> `CLAUDE.md`, or an existing wiki page?

- **Yes** → skip. Write nothing.
- **No** → write it.

This gate is the wiki's only defense against bloat. Apply it strictly.

| Capture | Skip |
|---|---|
| Decisions and the *reasons* behind them | Function signatures, file structure |
| Approaches that were tried and failed, and *why* | Code patterns (the code shows them) |
| Platform gotchas and workarounds | Anything in `CLAUDE.md` already |
| Capture-surface rankings, comparison tables | Re-narration of `git log` |
| Relationships between components | Step-by-step what-I-did blow-by-blow |
| Deferred work + the actual blocker | "We decided to use X" without the why |

## Workflow — `handoff`

1. Pre-flight.
2. **Inventory the session.** From the conversation, list:
   - New things introduced → entity pages
   - Concepts/techniques that recur → concept pages (non-trivial only)
   - External sources cited → source pages (only if a `raw/` doc exists)
   - Existing pages that need an update
   Apply the **non-derivable gate** to every item before writing.
3. **Write the pages.** Follow the schema's frontmatter and link style.
   Be terse — a 5-line page is fine.
4. **Update the index.** One line per new page in the right category.
5. **Append to the log.** Format: `## [YYYY-MM-DD] <op> | <short title>`
   followed by 1–3 lines.
6. **Git on** → commit per scope (`wiki: <subject>`), push, verify
   `git status` clean.
   **Git off** → tell the user the files are written but not versioned;
   suggest `git init` if they want handoff durability across machines.

## Workflow — `snapshot`

The point of `snapshot` is to make `/compact` safe: persist the
load-bearing facts to wiki *before* compacting, so the compactor doesn't
need to recall them.

1. Pre-flight.
2. **Diff the session.** What's *new* since this conversation started
   that isn't already in the wiki? Apply the non-derivable gate.
3. **Write only the deltas.** Skip the full index overhaul that `handoff`
   does — just write the new/extended pages and append one log line:
   `## [YYYY-MM-DD] snapshot | <subject>`.
4. **Produce the recommended `/compact` string** and show it verbatim:
   ```
   /compact focus on <current task>. The following are now persisted in the wiki — drop from active window:
   - <wiki/page-1.md> — <what it covers>
   - <wiki/page-2.md> — <what it covers>
   Keep in window: <current diff / test failures / in-progress artifact>.
   ```
5. **Don't push** in snapshot mode unless the user asks. Optional commit
   is fine; default is no commit, just files on disk.

## Frontmatter (default — verify against schema)

```yaml
---
title: <page title>
type: entity | concept | source | comparison | overview | note
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [list of raw/ filenames cited, or []]
tags: [optional]
---
```

## Page Type Quick Reference (default — verify against schema)

| Path | Use when | Body shape |
|---|---|---|
| `wiki/entities/<name>.md` | A concrete *thing* exists in the project | What it is, layout, surface area, cross-refs, open follow-ups |
| `wiki/concepts/<name>.md` | A non-trivial idea/technique that recurs | Definition, when to apply, gotchas |
| `wiki/sources/<slug>.md` | Summarizing a `raw/` document | One-paragraph summary + key points + link to raw |
| `wiki/comparisons/<name>.md` | Comparing two or more approaches | Tradeoff table, recommendation |

If the project uses a flat `wiki/<topic>.md` layout, ignore the path
column and write flat.

## Pre-push Sanity (git only)

Before `git push`, in this order:

1. `git status` — only the files you intended.
2. `git log --oneline -5` — commit messages match project style.
3. `git diff origin/<branch>..HEAD` — review what's about to land.

If a commit message reads "what I did" instead of "what changed and
why", reword before pushing.

## Common Mistakes

- **Skipping schema discovery.** Always run it first; defer to whatever
  it returns over this skill's defaults.
- **Bootstrapping a parallel layout.** If `wiki/` already has files but
  no schema file, *do not* `mkdir` new subdirs — read the existing
  layout and write a schema file that matches it.
- **Overwriting existing pages.** Read them first; extend.
- **Padding with code or file structure.** That's already in the code
  and `git log`. The wiki captures *why* and *what surprised us*.
- **Forgetting the `log.md` entry.** Without it, the operation is
  invisible to a `grep "^## \["` audit.
- **Forgetting the index.** New pages must be discoverable from the
  catalog, not just by file scan.
- **Relative dates.** "Today" / "yesterday" / "Thursday" rot. Always
  write the absolute YYYY-MM-DD.
- **Committing but not pushing in `handoff`.** A handoff that lives only
  on your machine is not a handoff.
- **Pushing in `snapshot` without asking.** Snapshot is mid-session; the
  user may not want a remote commit yet.
- **Single mega-commit.** Match the project's split style — one commit
  per scope (e.g. one for code, one for `wiki:`).
- **Skipping the non-derivable gate.** The wiki bloats fast if every
  session writes a play-by-play. Be ruthless.

## Red Flags — Stop and Fix

- About to write without locating the schema → run Schema Discovery first.
- About to bootstrap when `wiki/` already has content → infer the
  existing layout instead and write a matching schema.
- About to write `## [today]` or `## [yesterday]` → use the absolute
  YYYY-MM-DD.
- Page has no inbound links from `index.md` → orphan; add the index entry.
- Commit message is `update wiki` → too vague; name the page or topic.
- `git push` fails for auth → don't `--force`; ask the user.
- In `snapshot` mode but the recommended `/compact` string is missing →
  that bridge is the whole point of snapshot; produce it.
- Bootstrap step about to fetch from a URL → wrong; the seed is bundled
  at `seeds/llm-wiki.md`.