Kb init
Use to initialize or refresh the project's Knowledge Base at `kb/`. Creates the six canonical MD files (product, architecture, rules, principles, glossary, decisions) plus a README, creates `CLAUDE.md` at repo root if missing, and idempotently adds a Knowledge Base reference section to `CLAUDE.md` (or `AGENT.md` if that exists instead). Idempotent — safe to re-run.From its SKILL.md
npx -y skills add Navdeepgambhir9023/nav --skill kb-initAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.5 KB, as published. Nobody here has run it
{OWNER} — who Nav is addressing
Wherever this skill says {OWNER}, substitute the label field from
.loop/config.json. Default: founder. Capitalize it when it begins a
sentence or heading, and never emit the literal string {OWNER} to the user.
This is vocabulary only. No gate, threshold, default, or question differs
between profiles — an engineer and a founder get exactly the same engine.
If .loop/config.json is missing or unreadable, use "founder" and continue;
never halt on it.
/kb-init — Initialize the Knowledge Base
The KB is project self-description: what the product is, how it's built, what rules govern it, what vocabulary it uses, and why key choices were made. This skill ensures the KB exists and is wired into the agent's startup context.
<HARD-GATE> CONSTRAINTS (Must follow): - Do NOT overwrite an existing `CLAUDE.md` (or `AGENT.md`) — only append or replace the KB reference section. - Do NOT delete or rewrite existing `kb/*.md` files — only create them if missing, or add a header/footer note that the file was touched. - Do NOT promote this skill into a tool that "fills in" the KB on the {OWNER}'s behalf — content is the {OWNER}'s job. This skill only creates the scaffolding. - Do NOT require CLAUDE.md to be created if `AGENT.md` exists — the {OWNER}'s intent is honored. </HARD-GATE>Anti-Pattern: "Just Fill In the KB"
A scaffolding skill is not a content skill. /kb-init creates the
files with prompts and example placeholders. The actual content — what
the product is, what rules apply — is the {OWNER}'s responsibility
(and /kb-re-structure's, when reorganizing free-form dumps). Do not
let this skill invent product truth.
Process Summary
- Detect repo root — walk up from cwd to find the directory containing
.claude/or.git/. - Create
kb/if missing, plus the six canonical MD files (product.md,architecture.md,rules.md,principles.md,glossary.md,decisions.md) and aREADME.mdindex — all with prompt-only scaffolds (no fabricated content). - Detect
CLAUDE.md/AGENT.mdat repo root — prefer CLAUDE.md; fall back to AGENT.md if CLAUDE.md is absent. - If neither file exists — create CLAUDE.md from scratch with a KB reference section.
- If the file exists — find or create a
## Knowledge Basesection; replace its contents (idempotent) with the canonical reference block pointing to each kb/*.md. - Report what was created or updated.
Checklist
1. Detect Repo Root
- Find the repo root — start at cwd, walk up. Repo root = directory containing
.claude/,.git/, orpackage.json. If none found, halt and ask the {OWNER} to run from a project directory. - Set
REPO_ROOTfor the rest of the checklist.
2. Create kb/ Scaffolding
- Create
kb/if missing (mkdir -p). - Create each canonical file if missing — use the canonical scaffolds in
kb-init/scaffolds/. Do not overwrite existing files; skip them and report. - Create
kb/README.mdwith the index table mapping files to purposes.
The canonical scaffolds are the source of truth for KB file format. If this skill is invoked on a project that already has a KB structure the {OWNER} curated, leave it alone — only add files that are missing.
3. Detect Agent Entry-Point File
- Check
CLAUDE.mdat$REPO_ROOT/CLAUDE.md— if present, use it. - Else check
AGENT.md— if present, use it. - If neither — note that step 4 will create CLAUDE.md.
The two-file convention exists because some tooling (Claude Code, Cursor, Windsurf) reads CLAUDE.md while others (Aider, generic agents) read AGENT.md. The {OWNER}'s choice is preserved.
4. Write or Update the Reference Section
- If file is being created from scratch — write CLAUDE.md with:
- A
# <Project Name>header (use the directory name as default; {OWNER} can rename) - A
## Knowledge Basesection with the canonical reference block - A short note: "This file is generated by
/kb-init. Edit freely — only the## Knowledge Basesection is managed by the skill."
- A
- If file exists — find a
## Knowledge Baseheading. If present, replace everything between it and the next##heading (or EOF) with the canonical reference block. If absent, append the section at end of file. - Canonical reference block:
## Knowledge Base
The `kb/` folder at the repo root holds project self-description.
Read all six files at the start of any non-trivial task. They are
the canonical source for product truth, architecture, rules,
vocabulary, and decisions.
- `kb/product.md` — what this product is, who it's for, what it does, what it doesn't
- `kb/architecture.md` — components, data flow, storage, dependencies, design choices
- `kb/rules.md` — project-level rules (mandatory)
- `kb/principles.md` — durable judgment calls and trust-boundary paths
- `kb/glossary.md` — terminology
- `kb/decisions.md` — ADRs (architecture decision records)
The KB must be updated whenever `/loop` closes a goal that built a new
module, added a new rule, or changed architecture. See
`skills/loop/SKILL.md` step 24b.
5. Report
- Print a one-paragraph summary of what was created or skipped. List every file touched and every file left alone.
Process Flow
digraph kb_init {
"Detect repo root" [shape=box];
"Repo root found?" [shape=diamond];
"Halt: run from a project directory" [shape=box];
"Create kb/ + 6 MDs + README" [shape=box];
"CLAUDE.md exists?" [shape=diamond];
"AGENT.md exists?" [shape=diamond];
"Create CLAUDE.md from scratch" [shape=box];
"Update KB section in chosen file" [shape=box];
"Print summary" [shape=doublecircle];
"Detect repo root" -> "Repo root found?";
"Repo root found?" -> "Halt: run from a project directory" [label="no"];
"Repo root found?" -> "Create kb/ + 6 MDs + README" [label="yes"];
"Create kb/ + 6 MDs + README" -> "CLAUDE.md exists?";
"CLAUDE.md exists?" -> "Update KB section in chosen file" [label="yes"];
"CLAUDE.md exists?" -> "AGENT.md exists?" [label="no"];
"AGENT.md exists?" -> "Update KB section in chosen file" [label="yes"];
"AGENT.md exists?" -> "Create CLAUDE.md from scratch" [label="no"];
"Create CLAUDE.md from scratch" -> "Print summary";
"Update KB section in chosen file" -> "Print summary";
}
The terminal state is printing the summary.
Canonical Scaffolds
The KB scaffolds live in kb-init/scaffolds/. Each file is a prompt
for the {OWNER}, not invented content:
product.md— "What is this product? Who is it for? What does it do? What does it explicitly NOT do?"architecture.md— "How is it built? What are the major components? How does data flow? What's stored where?"rules.md— "What project-level rules must every contributor and agent obey?"principles.md— "When the rules don't decide it, what bias should resolve the trade-off? Which paths are trust boundaries?"glossary.md— "What terms appear in code, contracts, or prompts that a new reader wouldn't immediately understand?"decisions.md— "What non-obvious choices shaped this codebase?"
When /kb-init runs and any of these files already exist with content,
the {OWNER}'s content wins — the file is not touched.
Self-Review Checklist
After running:
kb/exists at repo root with all six canonical files.kb/README.mdis present and lists all six files.CLAUDE.mdorAGENT.mdexists at repo root (whichever the {OWNER} prefers).- KB reference section is present in the chosen file with the canonical block.
- No existing content overwritten —
CLAUDE.mdsections other than## Knowledge Baseare untouched.
Red Flags — STOP
- About to invent product truth (filling in
product.mdwith made-up facts). - About to overwrite an existing CLAUDE.md or AGENT.md.
- About to delete or rewrite an existing
kb/*.mdthat has {OWNER} content. - About to run from a directory with no
.claude//.git/package.json(run from a project). - About to skip the idempotency check and re-create files that already exist.
Relationship to Other Skills
| Skill | When it runs | Relationship |
|---|---|---|
/kb-init | {OWNER} invokes when setting up a project or refreshing KB scaffolding | Creates the structure, not the content |
/kb-re-structure | {OWNER} dumps free-form notes; invokes this to organize them into the KB | Reorganizes existing content into the canonical files; does not invent |
/loop | At every goal CLOSE | Step 24b requires KB update if the goal changed product/architecture/rules |
/goal, /plan, /verify | Every run | Read KB files via the "Before You Start" preamble (cross-referenced from CLAUDE.md) |
The Bottom Line
The KB is the project's living self-description. /kb-init is the
spine. {OWNER} content is the muscle. /kb-re-structure is the
reorganizer. /loop keeps it current.
Re-running /kb-init is always safe — it's idempotent. But respect
existing {OWNER} content: scaffolding is the skill's job, truth is
the {OWNER}'s.