agentleFS
smoketurnersmoketurner/claude-okf-kb/.claude/skills/kb-refresh/SKILL.md

kb-refresh

Skill0 starsChanged 3 days agoMITView on GitHub

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.

  • Deletes or force-pushes

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 2 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read the printed manifest.json.

    line 23
  2. Very specific:

    Read tool_report (the cross-session tool-use summary: per-tool call/error counts, a Bash-executable breakdown, and redacted error snippets).

    line 48
  3. Very specific:

    When an error pattern matches an existing gotchas/ concept, do not skip it as "already documented" — the concept exists but is not …

    line 56
  4. Very specific:

    Search the current bundle first: grep kb_manifest titles/descriptions and the concept bodies (rg -i the key symbols across the type dirs) …

    line 66
  5. Very specific:

    If an existing concept covers the topic, UPDATE it via the CAS protocol in AGENTS.md: read its (version, content_sha256), merge the new …

    line 68
  6. Very specific:

    If genuinely new, create it in the right type dir at version: v1 per AGENTS.md, then stamp.

    line 79
  7. Very specific:

    Recency wins on contradictions: when a new session contradicts an existing concept's current-state claim, the newer session is …

    line 81
  8. Very specific:

    Run uv run scripts/okf.py index <changed dirs> and uv run scripts/okf.py validate (fix everything it flags).

    line 91
  9. Very specific:

    Every reviewed path goes in reviewed regardless of outcome.

    line 114
  10. Distinctive:

    Read the last ~5 refresh run records in log.md and skim a sample of concepts you touched, plus the step-6 review outcomes.

    line 119
  11. Very specific:

    Write <run_dir>/metrics.json:

    line 128
  12. Distinctive:

    If the run processed sessions but created/updated no concepts (only the watermarks, usage records, and log advanced), that is a valid …

    line 157

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 — 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>", path: "<provenance>", last_modified: "<last timestamp>", project: "<repo>"} for a transcript digest (a <session>--agent-<id> digest cites the parent <session> uuid and path), {resource: "<repo>/.local/<relpath>", path: ..., last_modified: ..., project: ...} for a local--* digest, or {resource: "memory:<file>.md", path: ..., last_modified: ..., project: ...} for a memory--* digest — where path is the digest header's provenance: line verbatim and last_modified is its last dates:/modified: timestamp — 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 + superseded_by 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 (ordered by the later of each concept's newest verified[].at and its 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 — append { by: kb-refresh/<your model id>, at: <now, ISO 8601 UTC> } to its verified list via CAS (bump version, leave generated alone, stamp) and 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 superseded_by 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 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, 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 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.