ckb/.agents/skills/ckb-init/SKILL.md

name

description

ckb-init

Bootstrap a brand-new Cascade Knowledge Base - the same directory structure, AGENTS.md/CLAUDE.md system prompt, full default skill set, LICENSE/VERSION, and empty wiki/ scaffold as this project - inside a target folder (typically empty, or a new project that doesn't have one yet). Use when the user asks to "set up a new wiki like this one", "initialize a new cascade KB", "bootstrap a wiki here", "create a knowledge base with this schema", or calls it a "wiki initializer". Do not confuse with a generic `init` skill that documents an existing codebase - this one creates the Cascade KB pattern itself, empty, ready for its first ingest. Distinct from `ckb-upgrade`, which catches an *existing* populated KB up with template changes rather than bootstrapping a new one.

Cascade KB init skill

Purpose

Copy this project's Cascade Knowledge Base schema - not its content - into a new target folder: the directory structure, the AGENTS.md/CLAUDE.md system prompt that defines how the KB behaves, the full default skill set, LICENSE and VERSION, the generic README/MANUAL docs, and the empty wiki/ scaffold (routing table, overview, log, error book, entity/graph indexes). The result is a new, empty KB that behaves exactly like this one, ready for its first raw/inbox/ drop and "Ingest."

This is a one-way copy from this repo's own template files into a different folder. It never reads or writes anything in this repo's raw/, wiki/entities/, wiki/graph/edges.json, or outputs/ - those hold this project's actual accumulated knowledge, which is exactly what should not travel into a fresh KB. (For catching an already-populated KB up with newer template files without losing its accumulated content, see ckb-upgrade instead - that skill does the same source-of-truth copying this one does, but merges it into an existing KB rather than a blank folder.)

Trigger phrases

• "set up a new wiki like this one" / "initialize a new cascade KB"
• "bootstrap a wiki here" / "create a knowledge base with this schema"
• "wiki initializer" / "clone this KB structure into a new project"

How to run this skill

Step 1 - Confirm the target folder

Ask (if not already given): "Which folder should I initialize the new knowledge base in?" Resolve to an absolute path. This is a filesystem action outside the current repo, so confirm the resolved path back to the user before writing anything - do not assume a relative path means "somewhere under the current project."

If the folder doesn't exist yet, create it after confirming the path. If it exists, check its contents before doing anything else (Step 2).

Step 2 - Don't clobber an existing KB or unrelated project

If the target already contains a wiki/ directory, or an AGENTS.md / CLAUDE.md, stop and ask: "This folder already looks like it has a knowledge base (found <what>). Initializing here could overwrite it. Do you want to proceed anyway, pick a different folder, or only add whatever scaffold pieces are missing?" Never silently overwrite an existing AGENTS.md or populated wiki/ tree.

If the target has other, unrelated files (e.g. it's an existing code project without a KB yet) - that's fine, proceed; the scaffold is added alongside them. Note any top-level name collisions (e.g. an existing wiki/ folder used for something else) and ask before touching those specifically.

Step 3 - Default skill set (no need to ask)

The bare scaffold (directory structure + AGENTS.md/CLAUDE.md + empty wiki/ templates) is always included, and so is the full reusable KB skill set - these operate purely on the wiki/ structure (or, for ckb-init and ckb-upgrade themselves, on the schema layer), so they carry over cleanly and are part of "the schema" as far as this skill is concerned. As of this writing, that's every skill under this repo's .agents/skills/:

• ckb-init (this skill - a new KB can bootstrap further KBs of its own)
• ckb-upgrade (lets the new KB catch up with template changes later)
• ckb-ingest
• ckb-lint
• ckb-sync-changes
• ckb-project-summary
• ckb-export-okf
• ckb-export-starlight
• ckb-onboard-me
• ckb-teach-me
• cbk-quiz

Don't ask about any of these - just include them.

If, at the time this skill runs, .agents/skills/ also contains skills not in the list above, they're either a newer schema-native addition this document hasn't been updated to mention yet (safe to fold into the default set the same way - they follow the same "operates purely on the KB structure" test) or a project-specific/general-purpose skill someone added for this project only (e.g. a brand-specific export tool or a general writing aid, unrelated to the Cascade KB pattern itself) - in that case, only include it if the user explicitly asks for it by name, e.g. "also bring over <skill-name>."

Record the final skill list (the defaults above, plus anything explicitly added) - this affects Steps 8 and 9.

Step 4 - Create the directory structure

Under the target folder, create:

libs/
linked/
outputs/
raw/inbox/
raw/archive/
tmp/
wiki/entities/
wiki/graph/
workload/

Git doesn't track empty directories, so every one of these - plus .agents/, .agents/skills/, and .claude/ created in Step 9 - needs a placeholder to survive a fresh git init and first commit. This repo's own convention is an empty file named .gitadd in each directory (not .gitkeep) - match that convention exactly, so a new KB's directory listing looks identical to this one's.

libs/ and tmp/ are gitignored per the schema (Step 8) except for their own .gitadd placeholder, so they stay effectively empty. linked/ gets a .gitadd too but is not gitignored - it's meant to hold real symlinks, which git tracks natively (as a small blob storing the link target), so nothing extra is needed there. raw/inbox/, raw/archive/, and workload/ are meant to be tracked and start genuinely empty aside from their placeholder.

Step 5 - Write AGENTS.md and the CLAUDE.md symlink

Copy this repo's AGENTS.md verbatim into the target as AGENTS.md - it is already fully generic (no project-specific content; it is the schema definition). Then create CLAUDE.md in the target as a symlink to AGENTS.md, matching this repo's own convention (one source of truth, readable under either filename).

Step 6 - Write LICENSE, VERSION, and the generic docs

Copy these verbatim from this repo - they're already fully generic (no project-specific content, confirmed by having zero references to any actual project entity):

• README.md and README.pl.md - the technical feature overview, including the "source repo" pointer at the top. Leave that pointer as-is (pointing at this template's own canonical repo) unless the user says the new KB should point somewhere else - it's what lets the new KB's own ckb-upgrade find template updates later.
• MANUAL.md and MANUAL.pl.md - the task-oriented user guide.
• VERSION - copy the exact current value; the new KB starts life on the same template version it was just cloned from.

For LICENSE, copy the Apache License 2.0 text, but ask the user first whether to keep the copyright line as-is (appropriate if this new KB is still effectively part of the same umbrella/organization) or update it to their own name/organization (appropriate if this is a genuinely separate project that will accumulate its own content under its own ownership) - don't silently carry over a copyright attribution that may not apply to what the new KB is about to collect.

Step 7 - Write the empty wiki/ scaffold

Create these files in the target, using this repo's current versions as the template and stripping every reference to this project's actual content (Grant Thornton, Cloud Drift, specific entities, etc.) down to the generic structure:

• wiki/index.md - frontmatter with kb_schema_version: "1.1" only. Body: the routing table with just its four fixed infrastructure rows (Overview, Log, Error Book, Entities, Graph) and no entity rows, plus the "## Entity Pages" section with its placeholder note. Use today's date where the template needs one.
• wiki/overview.md - copy verbatim from this repo (it's already generic - directory tree, cascade priority, frontmatter summary, no project content). Set last_updated to today.
• wiki/log.md - header and explanation only, no entries.
• wiki/error-book.md - copy verbatim (already generic: empty table
  • placeholder note). Set last_updated to today.
• wiki/entities/index.md - header + placeholder note, no entries.
• wiki/graph/index.md - header + pointer to edges.json, with a generic "Current graph coverage: (none yet)" line instead of this repo's specific bullet list.
• wiki/graph/edges.json - {"version": 1, "last_updated": "<today>", "edges": []}.

Do not carry over any entity pages, graph edges, log entries, or overview content specific to this project - the whole point is an empty KB with the same shape.

Step 8 - Write .gitignore

Copy this repo's actual current .gitignore verbatim rather than reconstructing it from memory - it uses a <dir>/* + !<dir>/.gitadd pairing (not a bare <dir>/ line) for directories that should exist as a tracked shell but have their real contents ignored:

libs/*
!libs/.gitadd
tmp/*
!tmp/.gitadd
outputs/starlight
outputs/okf
outputs/teaching
.env

Since ckb-export-starlight, ckb-export-okf, and ckb-teach-me are all in the default skill set (Step 3), their outputs/ subfolders (outputs/starlight, outputs/okf, outputs/teaching) are gitignored by default too - each exists to be ignored precisely because its skill is present by default. If a future skill set change ever drops one of those three skills from the default set, drop its matching ignore line too; if the user explicitly adds a skill with its own outputs/<x> convention, ask whether it needs a similar ignore line.

Step 9 - Copy the skill set from Step 3

Copy each skill's folder from this repo's .agents/skills/<name>/ into the target's .agents/skills/<name>/ unchanged (including each skill's own license footer, and any support files like ckb-export-starlight/scripts/export_starlight.py) - the full default set from Step 3, plus anything explicitly added. Then create .claude/skills in the target as a symlink to ../.agents/skills, matching this repo's convention - do this once, after copying the whole set, not per-skill.

Step 10 - Report

Tell the user:

• The resolved target path.
• The directory tree created.
• Whether AGENTS.md/CLAUDE.md were written or (per Step 2) skipped/merged.
• Which skills were copied (the full default set, plus anything explicitly added).
• The VERSION the new KB starts on, and what was decided for LICENSE's copyright line.
• Next step: "Drop material into raw/inbox/ and say 'Ingest' to populate the wiki for the first time."

Edge cases

• Target is the current repo itself, or a parent/ancestor of it - refuse and explain why: this would either overwrite the live KB you're running from, or nest a KB inside itself. Ask for a genuinely separate path.
• Target is on a different filesystem/drive or requires elevated permissions - if directory creation fails, report the exact error rather than retrying with escalated permissions.
• User wants only some of the wiki template files (e.g. just the directory structure, no AGENTS.md) - honor that; the steps above are the default full scaffold, not an all-or-nothing bundle.
• This repo's own AGENTS.md or template wiki/ files have since drifted from each other (e.g. one mentions a directory the other doesn't) - fix the drift in this repo first if noticed, then copy the corrected version. Don't propagate a known inconsistency into a new KB.

---

Licensed under the Apache License, Version 2.0 — see LICENSE at the repository root, or http://www.apache.org/licenses/LICENSE-2.0.