Skip to content
Skills Library
AI & agents · Automation

kb-refresh

/kb-refresh

Incrementally refresh new Claude Code sessions into this OKF knowledge base and self-improve it. Use when asked to update/refresh the KB from recent sessions, or run the periodic refresh by hand. Reads the recorded watermarks, mines only newer sessions (both their text and their tool-use patterns), applies updates via the compare-and-set protocol, reviews existing concepts for staleness, runs a quality gate, reflects on its own criteria, and proposes the result as a pull request.

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Incrementally refresh new Claude Code sessions into this OKF knowledge base and self-improve it. Use when asked to update/refresh the KB from recent sessions, or run the periodic refresh by hand. Reads the recorded watermarks, mines only newer sessions (both their text and their tool-use patterns), applies updates via the compare-and-set protocol, reviews existing concepts for staleness, runs a quality gate, reflects on its own criteria, and proposes the result as a pull request.

Original author description

Incrementally refresh new Claude Code sessions into this OKF knowledge base and self-improve it. Use when asked to update/refresh the KB from recent sessions, or run the periodic refresh by hand. Reads the recorded watermarks, mines only newer sessions (both their text and their tool-use patterns), applies updates via the compare-and-set protocol, reviews existing concepts for staleness, runs a quality gate, reflects on its own criteria, and proposes the result as a pull request.

How it works

  1. 1. Prepare (deterministic)
  2. 2. Mine facts (fan-out)
  3. 3. Mine tool-use patterns
  4. 4. Reconcile against the current KB (CAS)
  5. 5. Quality gate
  6. 6. Review existing concepts (staleness + pruning)
  7. 7. Reflect (self-improvement)
  8. 8. Metrics, proposal summary + finalize
  9. 9. Propose (pull request)
Original SKILL.md headings · 157 lines, 1,528 words
SKILL.md preview
---
name: kb-refresh
description: Incrementally refresh new Claude Code sessions into this OKF knowledge base and self-improve it. Use when asked to update/refresh the KB from recent sessions, or run the periodic refresh by hand. Reads the recorded watermarks, mines only newer sessions (both their text and their tool-use patterns), applies updates via the compare-and-set protocol, reviews existing concepts for staleness, runs a quality gate, reflects on its own criteria, and proposes the result as a pull request.
---

# Knowledge-base refresh loop

You maintain this knowledge base by folding newly-recorded coding sessions into it. Run from the
knowledge-base repo root (the directory holding `kb.config.json`; if it is missing, stop and tell
the user to run `/kb-init` first). Read `kb.config.json` for the project name and the
`source_repos` whose sessions you mine and whose code is ground truth, then read
[AGENTS.md](/AGENTS.md) — it defines the frontmatter contract, the inclusion bar, and the
compare-and-set (CAS) update protocol you MUST follow.

Work top-to-bottom. Keep the bundle valid at every step (`uv run scripts/okf.py validate`). You apply
changes to the working tree only — you do **not** commit or push; the result is proposed as a PR
(step 9) so a human reviews before anything lands.

## 1. Prepare (deterministic)

Run: `uv run scripts/refresh.py prepare`

Read the printed `manifest.json`. If `new_sessions`, `local_artifacts` and `memory_files` are all
0, there is nothing to do — report that and stop. Otherwise note `run_dir`, `batches`, `kb_manifest`
(current concepts), `tool_report`, `tool_calls`/`tool_errors`, `review` (the existing concepts to
verify in step 6), and `kb_reads` (how many concepts the new sessions read — the per-concept counts
are in the manifest's `usage` file). `prepare` has already digested and **secret-redacted** the new
sessions and artifacts; never try to recover a `[REDACTED]` value.

## 2. Mine facts (fan-out)

For each batch, read every digest listed in its manifest file and extract durable facts, applying the
inclusion bar from AGENTS.md verbatim (decisions+rationale, dead-ends, user corrections, gotchas that
took >1 exchange, operational/env knowledge, external-API/spec quirks; exclude anything reconstructible
from current code, one-off fixes, trivia). Cap ~10 facts per batch; each needs a concrete transcript
quote as evidence. Digests named `<session>--agent-<id>.md` are subagent transcripts: the parent
session holds the user's words, the subagent holds the implementation work, and both earn facts.
Batches may also list `local--*.md` digests — settled artifacts agents wrote to `<repo>/.local/`
(top-level `*.md` and `plan{,s}/`); apply the same inclusion bar, quoting the artifact itself as
evidence. They may also list `memory--*.md` digests — the per-project Claude memory files under
`~/.claude/projects/<project>/memory/`, already distilled, so most of their content clears the bar;
a memory file is re-mined whenever it changes, so first find the concept that already cites
`memory:<file>.md` and fold the change in via CAS. With more than ~4 batches, run these as a
Workflow fan-out; otherwise mine inline.

## 3. Mine tool-use patterns

Read `tool_report` (the cross-session tool-use summary: per-tool call/error counts, a Bash-executable
breakdown, and redacted error snippets). Look for **systematic** patterns a single session can't reveal:
a tool erroring repeatedly across sessions, a recurring misconfiguration (e.g. a command that keeps
being denied or a flag that keeps failing), or a workflow that consistently wastes turns. Capture only
durable, actionable ones as `gotchas/` or `conventions/` concepts (e.g. "tool X needs config Y", "avoid
Z, it fails under W") — verify against the live source before asserting a cause. Ignore one-off errors.
A high error rate with no clear systematic cause is not a fact.

When an error pattern matches an **existing** `gotchas/` concept, do not skip it as "already
documented" — the concept exists but is not preventing the failure. Check its entry in
`.refresh/usage.json`: zero reads means a discoverability problem (rewrite its title/description so
it is findable by the symptoms someone would search for); nonzero reads with the error still
recurring means a content problem (correct or sharpen the advice). Apply as a CAS update and count
it in `recurring_gotchas`.

## 4. Reconcile against the current KB (CAS)

For each candidate fact (from step 2 or 3), decide **new concept** vs **update of an existing one**:
- Search the current bundle first: grep `kb_manifest` titles/descriptions and the concept bodies
  (`rg -i` the key symbols across the type dirs) before concluding a fact is new.
- If an existing concept covers the topic, UPDATE it via the CAS protocol in AGENTS.md: read its
  `(version, content_sha256)`, merge the new knowledge (do not delete still-valid content), append a
  `sources` entry in **block YAML style** —
  `{resource: "session:<uuid>", last_modified: "YYYY-MM-DDT00:00:00Z", project: "<repo>"}` for a
  transcript digest (a `<session>--agent-<id>` digest cites the parent `<session>` uuid),
  `{resource: "<repo>/.local/<relpath>", last_modified: ..., project: "<repo>"}` for a `local--*`
  digest, or `{resource: "memory:<file>.md", last_modified: ..., project: "<repo>"}` for a
  `memory--*` digest — bump `version` by one, set `generated` to
  `{ by: kb-refresh/<your model id>, at: <now, ISO 8601 UTC> }`, then
  `uv run scripts/okf.py stamp <file>`.
- If genuinely new, create it in the right type dir at `version: v1` per AGENTS.md, then stamp. Its
  first tag is the repo scope (the source repo's basename, or `cross`).
- **Recency wins on contradictions**: when a new session contradicts an existing concept's current-state
  claim, the newer session is authoritative — correct the concept (keep decisions, mark
  `status: deprecated` + `supersedes` only when a decision was truly reversed). When unsure whether a
  claim is current, verify against the live checkouts listed in `kb.config.json` `source_repos` —
  the code is ground truth.
- For every concept you create or update, note how many of this run's digests evidenced it — you
  will report that in the proposal summary (step 8).

## 5. Quality gate

Run `uv run scripts/okf.py index <changed dirs>` and `uv run scripts/okf.py validate` (fix everything
it flags). Then check the concepts you created/updated for duplicates (merge or cross-link, don't leave
two), unresolved contradictions, and broken bundle-relative links. Keep changes tight and cross-link
related concepts bidirectionally.

## 6. Review existing concepts (staleness + pruning)

The manifest's `review` list holds the least-recently-verified existing concepts (selected from
`.refresh/review.json` dates, falling back to each concept's own `generated.at`; the slice size is
`review_slice` in `kb.config.json`). For each one, verify its current-state claims against the live
source repos. Outcomes:

- **Still accurate** — touch nothing; just include it in `reviewed` (step 8).
- **Stale claim** — correct it via the CAS protocol (also counts toward `updated`).
- **Duplicate** — merge into the surviving concept, then treat the loser as pruned below.
- **No longer earns its place** — a decision gets `status: deprecated` plus a `supersedes` link
  (decisions are never deleted); any other type is deleted, but do NOT delete files yourself:
  first `rg` the bundle for inbound links and fix them, then add its path to `pruned` in metrics —
  `finalize` performs the removal. Zero usage in `.refresh/usage.json` never justifies deletion by
  itself; treat it as corroboration only once the file's `since` date shows ≥60 days of tracking.

Every reviewed path goes in `reviewed` regardless of outcome. Re-run
`uv run scripts/okf.py index <dir>` for any directory you changed.

## 7. Reflect (self-improvement)

Read the last ~5 refresh run records in [log.md](/log.md) and skim a sample of concepts you touched,
plus the step-6 review outcomes. Ask: is the inclusion bar in AGENTS.md producing trivia or missing a
recurring category (now including tool-use patterns)? Is a type directory overflowing or a taxonomy
line unclear? Are reviewed concepts going stale in a systematic way? If — and only if — you see a
concrete, recurring signal, make one small edit to the inclusion bar or taxonomy in AGENTS.md
(bump its `version`, update `generated`, stamp it) and note it. Do not churn AGENTS.md without a clear signal.

## 8. Metrics, proposal summary + finalize

Write `<run_dir>/metrics.json`: `{"sessions": N, "local_artifacts": N, "memory_files": N,
"created": N, "updated": N,
"contradictions_fixed": N, "tool_patterns": N, "recurring_gotchas": N,
"reviewed": ["<type>/<slug>.md", ...], "pruned": ["<type>/<slug>.md", ...],
"reflection": true|false}`.

Then write `<run_dir>/proposal-summary.md` for the PR body: a `### Proposed concepts` heading, one
line per created/updated concept with its evidence prevalence —
`- created gotchas/foo.md — evidenced by 3 sessions this run` or
`- updated decisions/bar.md (v4 -> v5) — evidenced by 1 session this run, 6 total sources` (total =
length of its `sources` list) — plus one line summarizing step 6, e.g.
`- reviewed 10 concepts: 8 unchanged, 1 updated, 1 pruned`.

Then run `uv run scripts/refresh.py finalize --run-dir <run_dir>` — it advances the watermarks,
deletes the `pruned` files, merges the run's usage into `.refresh/usage.json`, records `reviewed`
dates in `.refresh/review.json`, and adds the run record under today's date in log.md, all **in the working tree**
(these land only when the PR merges). After finalize, re-run `uv run scripts/okf.py index <dir>`
for any directory a pruned file left, and validate must be clean.

## 9. Propose (pull request)

`uv run scripts/okf.py validate` must be clean and the quality gate must have no unresolved
high-severity contradiction. Then **do not commit or push** — hand off to the proposal script, which
branches, commits every change (concepts + watermark/log together), pushes, and opens a PR:

```
bash scripts/refresh-propose.sh
```

If the run processed sessions but created/updated no concepts (only the watermarks, usage/review
records, and log advanced), that is a valid outcome — the proposal script detects the
bookkeeping-only case and commits it straight to the base branch instead of opening a noise PR. Tell
the user whether it opened a PR or just recorded bookkeeping (or, if they'd rather discard, that `git checkout -- . && git clean -fd`
reverts the working tree). If anything blocked (validation failed, an unresolved contradiction,
secrets suspected), do NOT finalize or propose — revert the working tree with
`git checkout -- . && git clean -fd`, report what blocked, and stop so no bad state is proposed.

Versions

The database has no other skills named kb-refresh.

Database snapshot: 13.11.2026 · package version 08de7f7d4a9a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100okf-distill
    Use when the user asks to turn past Claude Code or Codex sessions into durable knowledge documents — "distill the api-refactor session into the knowledge base", "extract the decisions from yesterday's sessions as OKF nodes", "write up what we learned in 019dc08e". For…
  • 100okf-distill
    Use when the user asks to turn past Claude Code or Codex sessions into durable knowledge documents — "distill the api-refactor session into the knowledge base", "extract the decisions from yesterday's sessions as OKF nodes", "write up what we learned in 019dc08e". For…
  • 100okf-wiki
    Builds an Open Knowledge Format (OKF) knowledge base from existing docs, notes, or a repo. Use to scaffold an OKF wiki.
  • 100refresh-okf-mcp-token
    Fetch or refresh an OAuth2 access token for the OKF Data wiki consumption MCP server. Use when the OKF MCP server returns 401/403/unauthorized/expired-token errors, when the user asks to refresh, renew, or get a new OKF MCP token, or when setting up authentication to call the…
  • 100kb-init
    Scaffold a new OKF knowledge base in the current repository that mines local Claude Code sessions for one or more source repos. Use when asked to initialize/create/set up a knowledge base, start a new "-kb" repo, or bootstrap this template. Gathers the project name and source…
  • 100okf-projection
    Creates, checks, refreshes and renders the knowledge projections of an OKF bundle (projections/<slug>/, ADR-0022), derivations of the base for a reader that are not OKF. Checks each projection.yaml, the dependency rule and drift by nature with okf_projection.py, proposes the…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.