55c8c352d1
libs/<name>/ now supports a second population mode alongside git-copy clones: a user-authored source.yaml declares a live external source (SharePoint, Google Drive, a plain URL, or another connector), and the new ckb-index-external skill builds a self-contained generated index for it (index.md/entities/graph/log.md), scoped entirely to that connector and never blended into the main wiki/. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
137 lines
6.3 KiB
Markdown
137 lines
6.3 KiB
Markdown
---
|
||
name: ckb-ingest
|
||
description: Process raw/inbox/ (or raw/ directly if the inbox is empty) into the structured wiki/ — consult the cascade, extract typed entities and relationships, synthesize frontmatted pages, cross-link them, update the index and log, then remind the user to review and sync to origin. Use when the user says "Ingest", "Sync the wiki", or "Update the Wiki". This is the content-level workflow from CLAUDE.md/AGENTS.md §3, distinct from the git-level `ckb-sync-changes` skill (which reconciles this repo's own history with its `origin` remote and does no wiki synthesis at all).
|
||
---
|
||
|
||
# Ingest skill
|
||
|
||
## Purpose
|
||
|
||
Turn raw, unstructured material in `raw/inbox/` (notes, links, pasted text,
|
||
scratch files) into the local, mutable, structured `wiki/` — the top layer
|
||
of the cascade that overlays read-only upstream KBs in `linked/` and
|
||
`libs/`. This is the primary way the wiki grows. It is implemented as a
|
||
skill (rather than living inline in `CLAUDE.md`/`AGENTS.md`) so the full
|
||
ingestion procedure only loads into context when actually invoked.
|
||
|
||
This skill only ever writes to `wiki/` (and moves processed files within
|
||
`raw/`). It never touches `linked/` or `libs/` — those are immutable
|
||
upstream sources of truth — and it never touches this repo's own git
|
||
remote; pushing the resulting changes is a separate, explicit step (see
|
||
Step 7).
|
||
|
||
## Trigger phrases
|
||
|
||
Use this skill when the user says:
|
||
- "Ingest"
|
||
- "Sync the wiki"
|
||
- "Update the wiki"
|
||
|
||
Do **not** use this skill for "sync changes", "sync with git/origin", or
|
||
"reconcile git" — those are git-level operations with nothing to do with
|
||
wiki content, handled by the `ckb-sync-changes` skill instead (see
|
||
`.agents/skills/ckb-sync-changes/SKILL.md`). This skill and that one are
|
||
deliberately separate: this one turns raw material into wiki pages; that
|
||
one commits/pulls/pushes whatever is currently on disk, wiki changes
|
||
included.
|
||
|
||
## How to run this skill
|
||
|
||
### Step 1 — Process the inbox
|
||
|
||
Scan `raw/inbox/` for new material. After ingesting each item, move it to
|
||
`raw/archive/<YYYY-MM-DD>/`, where the date is today's ingestion date
|
||
(create the dated folder if it doesn't exist yet).
|
||
|
||
If `raw/inbox/` is empty, scan `raw/` directly instead — excluding
|
||
`raw/archive/`, which holds material already processed by a previous
|
||
ingest.
|
||
|
||
### Step 2 — Consult the cascade
|
||
|
||
Before writing anything, check whether the entity already exists: local
|
||
`wiki/` first, then each `linked/<name>/`, then each `libs/<name>/`
|
||
(alphabetical within each layer). The local `wiki/` always wins — upstream
|
||
content is informative context, but it can be overridden locally rather
|
||
than treated as final.
|
||
|
||
### Step 3 — Extract entities
|
||
|
||
Identify typed entities in the source material — people, projects,
|
||
libraries, concepts, systems. Create entity pages at
|
||
`wiki/entities/<entity-name>.md` if they don't already exist. Record typed
|
||
relationships between entities — `uses`, `depends_on`, `caused`,
|
||
`contradicts`, `supersedes` — as edge data in `wiki/graph/edges.json`.
|
||
|
||
### Step 4 — Synthesize pages
|
||
|
||
Convert the core knowledge into clean, modular Markdown files. Every page
|
||
gets frontmatter with:
|
||
- A `tldr:` — one sentence, optimised for LLM reading.
|
||
- A `confidence:` score (0.0–1.0, based on source corroboration).
|
||
- A `quality:` self-score (0.0–1.0).
|
||
- A `last_updated:` timestamp.
|
||
- A `freshness_window_days:` appropriate to the topic.
|
||
- A `retention:` level.
|
||
|
||
`type` is also required (per the page frontmatter schema in
|
||
`CLAUDE.md`/`AGENTS.md` §2) — set it once, based on the entity/content
|
||
kind (person, project, concept, library, decision, playbook, ...).
|
||
|
||
### Step 5 — Link and cross-reference
|
||
|
||
Use **both** `[[Wikilinks]]` (Obsidian-compatible) and standard
|
||
`[markdown](path.md)` links on every cross-reference, so the wiki works in
|
||
Obsidian, GitHub, and CLI tools alike. Where useful, reference upstream
|
||
files directly at `linked/<name>/...` or `libs/<name>/...`.
|
||
|
||
### Step 6 — Update index and log
|
||
|
||
Add new pages to the routing table in `wiki/index.md` with a **Use when**
|
||
description. If the page lives in a subdirectory, also add it to that
|
||
subdirectory's own `index.md`. Append a log entry to the most specific
|
||
applicable log — the subdirectory's `log.md` if it has one, otherwise the
|
||
root `wiki/log.md` — following the format in Rule B (`CLAUDE.md`/
|
||
`AGENTS.md` §7).
|
||
|
||
If this step creates a brand-new `wiki/<topic>/` subdirectory, immediately
|
||
create that subdirectory's `index.md` per the Recursive Index & Log
|
||
Convention.
|
||
|
||
### Step 7 — Remind to review and sync
|
||
|
||
This is always the last step, every time this skill runs and made any
|
||
change at all. Close with a short reminder — do not sync or push
|
||
anything yourself here, and do not skip this even if the changes look
|
||
small or obviously correct:
|
||
|
||
> "Ingest complete — `wiki/` has been updated (see `wiki/log.md` for the
|
||
> details). Please review the changes, and once you're happy with them,
|
||
> say 'sync changes' to commit and push them to `origin`."
|
||
|
||
If nothing was actually ingested (empty inbox and empty `raw/`, nothing to
|
||
process), skip this reminder — there's nothing to review or sync.
|
||
|
||
## Edge cases
|
||
|
||
- **Inbox and `raw/` both empty** — report that there's nothing to
|
||
ingest. Don't touch `wiki/`, and skip the Step 7 reminder.
|
||
- **Item in inbox doesn't yield a clear entity or page** (too vague, pure
|
||
scratch note with no durable fact) — don't force a page into existence.
|
||
Still move the item to `raw/archive/<YYYY-MM-DD>/` since it's been
|
||
considered, but note in the ingest report that it produced no wiki
|
||
change.
|
||
- **Conflicting information vs. an existing local wiki page** — this is a
|
||
supersession case (Rule via `CLAUDE.md`/`AGENTS.md` §6 lint), not a
|
||
silent overwrite: update the existing page if the new source is clearly
|
||
more current/corroborated, and link `supersedes`/`superseded_by` if an
|
||
older version is worth preserving rather than edited in place.
|
||
- **Material duplicates an upstream (`linked/`/`libs/`) page with nothing
|
||
new to add** — don't create a redundant local page just to have one;
|
||
the cascade already surfaces the upstream page. Only write locally when
|
||
overriding, correcting, or adding to what upstream says.
|
||
|
||
---
|
||
|
||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|