Skip to content

Commit 5a58d6d

Browse files
committed
docs(readme): tighten Usage, add visualize/slides to Quick Start
Critical pass on Usage — it described the generators twice (Layer 2 table + narrative subsections): - drop the (i) Query & Chat and (iii) Visualize subsections (already in the Layer 2 table; depth is in examples/) - shorten Skill Factory to a flagship blurb + pointer (no walkthrough) - add the missing deck/slides generator to the Layer 2 table - fix the Skill Factory anchor link; remove a dead commented-out lint row Quick Start: add optional visualize + deck (deck noted as needing a theme). Claude-Session: https://claude.ai/code/session_018WiFnTo1YW9mtw47Fzir9K
1 parent cb280cf commit 5a58d6d

1 file changed

Lines changed: 9 additions & 45 deletions

File tree

README.md

Lines changed: 9 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -97,8 +97,10 @@ openkb query "What are the main findings?"
9797
# 5. Or chat interactively
9898
openkb chat
9999

100-
# (Optional) Distill a redistributable agent skill from your wiki
101-
openkb skill new my-expert "Reason like an expert on <your-topic>"
100+
# (Optional) Turn the wiki into other outputs
101+
openkb skill new my-expert "Reason like an expert on <your-topic>" # a portable agent skill
102+
openkb visualize # an interactive knowledge graph
103+
openkb deck new my-deck "An intro deck on <your-topic>" # slides (install a theme first — see examples/slides/)
102104
```
103105

104106
### Set up your LLM
@@ -191,7 +193,7 @@ A single source might touch 10--15 wiki pages. Knowledge accumulates: each docum
191193

192194
# ⚙️ Usage
193195

194-
OpenKB commands fall into two layers: the **wiki foundation** (compile + manage your knowledge) and **generators** (turn that wiki into useful output).
196+
OpenKB commands fall into two layers: the **wiki foundation** (compile + manage your knowledge) and **generators** (turn that wiki into useful output). These tables are the command inventory; step-by-step walkthroughs live in [`examples/`](examples/).
195197

196198
## Layer 1: 🧱 Wiki Foundation — compile and maintain
197199

@@ -214,8 +216,6 @@ OpenKB commands fall into two layers: the **wiki foundation** (compile + manage
214216
| <code>openkb&nbsp;recompile&nbsp;[&lt;doc&gt;]&nbsp;[--all]</code> | Re-run the compile pipeline on already-indexed docs without re-indexing. Regenerates summaries and rewrites concept pages; manual edits are overwritten (`--dry-run` to preview, `--refresh-schema` to also update `wiki/AGENTS.md`) |
215217
| <code>openkb&nbsp;feedback&nbsp;["msg"]</code> | File feedback by opening a prefilled GitHub issue (`--type bug/feature/question` to tag it) |
216218

217-
<!-- | `openkb lint --fix` | Auto-fix what it can | -->
218-
219219
</details>
220220

221221
## Layer 2: 💡 Generators — turn the wiki into output
@@ -228,7 +228,8 @@ A "generator" reads from the compiled wiki and produces something usable: an ans
228228
| <code>openkb&nbsp;chat</code> | Interactive multi-turn session over the wiki (`--resume`, `--list`, `--delete` to manage sessions) |
229229
| <code>openkb&nbsp;visualize</code> | A self-contained interactive knowledge graph at `output/visualize/graph.html` — 3D, mind-map, and radial views |
230230
| | |
231-
| <code>openkb&nbsp;skill&nbsp;new&nbsp;&lt;skill-name&gt;&nbsp;"&lt;intent&gt;"</code> | Distill a redistributable agent skill from your wiki (see [Skill Factory](#-skill-factory--drop-in-a-book-out-comes-a-digital-expert) below) |
231+
| <code>openkb&nbsp;skill&nbsp;new&nbsp;&lt;skill-name&gt;&nbsp;"&lt;intent&gt;"</code> | Distill a redistributable agent skill from your wiki (see [Skill Factory](#skill-factory) below) |
232+
| <code>openkb&nbsp;deck&nbsp;new&nbsp;&lt;name&gt;&nbsp;"&lt;intent&gt;"</code> | Generate a single-file HTML slide deck (`--skill` picks a theme, `--critique` runs a quality pass — see [`examples/slides/`](examples/slides/)) |
232233

233234
<details>
234235
<summary><i>More skill commands:</i></summary>
@@ -240,50 +241,13 @@ A "generator" reads from the compiled wiki and produces something usable: an ans
240241
| <code>openkb&nbsp;skill&nbsp;eval&nbsp;&lt;name&gt;</code> | Check the skill triggers on the right prompts |
241242
| <code>openkb&nbsp;skill&nbsp;history&nbsp;&lt;name&gt;</code> / <code>openkb&nbsp;skill&nbsp;rollback&nbsp;&lt;name&gt;</code> | Version history + rollback for skills |
242243

243-
See **[`examples/skills/`](examples/skills/)** for how validation, evaluation, and rollback actually work.
244-
245244
</details>
246245

247-
### (i) 💬 Query & Chat — *ask the wiki*
248-
249-
`openkb query "..."` answers a single question. `openkb chat` is interactive — each turn carries history, so you can dig into a topic without re-typing context. Both use the same underlying wiki and retrieval primitives.
250-
251-
```bash
252-
openkb query "What does the literature say about attention scaling?"
253-
254-
openkb chat # start a new session
255-
openkb chat --resume # resume the most recent session
256-
openkb chat --resume 20260411 # resume by id (unique prefix works)
257-
openkb chat --list # list all sessions
258-
openkb chat --delete <id> # delete a session
259-
```
260-
261-
Inside a chat, type `/` to access slash commands (Tab to complete) — `/add`,
262-
`/skill new`, `/save`, `/lint`, and more. See [`examples/chat/`](examples/chat/)
263-
for the full list.
264-
265246
<a id="skill-factory"></a>
266247

267-
### (ii) 🛠 Skill Factory — *drop in a book; out comes a digital expert.*
248+
### 🛠 Skill Factory — *drop in a book; out comes a digital expert.*
268249

269-
The newest generator. `openkb skill new` distills an [agent skill](https://docs.claude.com/en/docs/build-with-claude/skills) from any subset of your wiki, a portable folder that major agents (Claude Code, Codex, etc.) can install and load natively. Drop in a book's worth of papers; out comes a specialist that other agents can call on.
270-
271-
```bash
272-
openkb skill new karpathy-thinking \
273-
"Reason about transformers and attention in Karpathy's style"
274-
```
275-
276-
→ The output layout, local install, sharing via `npx skills add`, refining from
277-
chat, and the `validate` / `eval` / `history` / `rollback` quality gates are walked
278-
through in **[`examples/skills/`](examples/skills/)** — with a real generated skill.
279-
280-
### (iii) 🗺 Visualize — *see the shape of your knowledge*
281-
282-
`openkb visualize` renders the wiki as a single self-contained, offline HTML page with three views of the same knowledge base — a **3D** force graph, an OpenKB-rooted **mind-map**, and a **radial** tree — coloured by type and linked by `[[wikilinks]]`.
283-
284-
```bash
285-
openkb visualize # build + open output/visualize/graph.html
286-
```
250+
The flagship generator: `openkb skill new` distills a portable [agent skill](https://docs.claude.com/en/docs/build-with-claude/skills) from your wiki that Claude Code, Codex, and Gemini can install and load natively. Drop in a book's worth of papers; out comes a specialist other agents can call on. → A real generated skill, plus install / share / `eval` / rollback, is walked through in **[`examples/skills/`](examples/skills/)**.
287251

288252
# 🔧 Configuration
289253

0 commit comments

Comments
 (0)