Skip to content

Commit 49e463b

Browse files
karryKeksiskarryKeksis
committed
Initial commit
0 parents  commit 49e463b

3 files changed

Lines changed: 312 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Zread Skill
2+
3+
This repository contains a skill for `zread`, a CLI that generates wiki-style
4+
documentation for code repositories.
5+
6+
The skill is meant for one job: help an agent understand an unfamiliar codebase
7+
through `zread` output instead of re-reading the entire repository file by file.
8+
9+
## Installation
10+
11+
### 1. Install the zread CLI
12+
13+
Install `zread` first. There are two supported installation methods:
14+
15+
```bash
16+
npm install -g zread_cli
17+
```
18+
19+
or
20+
21+
```bash
22+
brew tap codegeex/homebrew-tap
23+
brew install zread
24+
```
25+
26+
Then verify the installation:
27+
28+
```bash
29+
zread version
30+
```
31+
32+
### 2. Install this skill
33+
34+
Ask your AI agent to install the skill from GitHub:
35+
36+
```text
37+
install this skill https://github.com/zread-ai/zread-skill
38+
```
39+
40+
If you prefer to install it manually, copy this directory into your local
41+
skills directory:
42+
43+
| Agent | Skills directory |
44+
| ----------- | ----------------------- |
45+
| Claude Code | `~/.claude/skills/` |
46+
| OpenClaw | `~/.openclaw/skills/` |
47+
| Codex | `~/.agents/skills/` |
48+
49+
Example:
50+
51+
```bash
52+
cp -R zread ~/.claude/skills/zread
53+
```
54+
55+
Your final layout should look like this:
56+
57+
```text
58+
<skills-dir>/zread/
59+
SKILL.md
60+
README.md
61+
references/
62+
stdio-protocol.md
63+
```
64+
65+
Once the folder is in place, an agent that supports `SKILL.md`-based skills can
66+
load and use it.
67+
68+
## Features
69+
70+
- Read existing `./.zread/wiki/` output instead of crawling source files again
71+
- Guide an agent to run `zread generate` safely when documentation does not
72+
exist yet
73+
- Use `--stdio` as the default mode for agent automation, instead of parsing
74+
the interactive TUI
75+
- Explain the role of `current`, `versions`, and `drafts` in zread output
76+
- Include a reference for the `zread --stdio` JSON-line protocol
77+
78+
## When To Use
79+
80+
Use this skill when you want to:
81+
82+
- understand an unfamiliar repository quickly
83+
- read an existing zread-generated wiki
84+
- generate a repository overview or project wiki
85+
- serve docs locally with `zread browse`
86+
- drive `zread` programmatically from a script or agent
87+
88+
## How It Works
89+
90+
The skill follows a simple workflow:
91+
92+
1. If `./.zread/wiki/current` exists, read the generated wiki files directly.
93+
2. If no wiki exists, run `zread generate` only when the user wants docs to be
94+
generated.
95+
3. Before generation, confirm with the user because generation consumes LLM
96+
tokens and writes under `./.zread/`.
97+
4. In automated workflows, use `--stdio`.
98+
99+
## Repository Layout
100+
101+
- `SKILL.md`: the skill definition, trigger conditions, and operating rules
102+
- `references/stdio-protocol.md`: the `zread --stdio` machine protocol
103+
- `appmap.log`: local artifact, not part of the skill itself
104+
105+
## zread Output
106+
107+
After a successful generation, zread typically writes:
108+
109+
- `./.zread/wiki/current`: the active wiki version id
110+
- `./.zread/wiki/versions/<id>/wiki.json`: the generated page index
111+
- `./.zread/wiki/versions/<id>/<file>`: the actual markdown pages
112+
- `./.zread/wiki/drafts/`: unfinished generation state
113+
114+
If you need to integrate with `zread` programmatically, see
115+
[references/stdio-protocol.md](./references/stdio-protocol.md).

‎SKILL.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
name: zread
3+
description: Produce and consume a wiki-style knowledge base for a code repository via the `zread` CLI and its on-disk output under `./.zread/wiki/`. Use this skill whenever the user wants to understand, onboard onto, explore, summarize, map, or get an overview of an unfamiliar codebase; asks for architecture docs, a project wiki, a repo walkthrough, module/package explanations, or "what does this repo do"; wants to generate, regenerate, resume, browse, or serve code documentation locally; or mentions zread / zread.ai directly. Also use it proactively before diving into a large unknown repo — if `./.zread/wiki/current` exists, read the generated pages instead of crawling source file-by-file; if it doesn't, consider offering to run `zread generate`. The trigger is the intent (understand a codebase through generated docs), not the literal word "zread".
4+
---
5+
6+
# zread skill
7+
8+
`zread` is a CLI that generates wiki documentation from code in the current
9+
workspace using an LLM. Output lives under `./.zread/wiki/` in the workspace;
10+
public repos can also be viewed at https://zread.ai.
11+
12+
This skill is intended for agent use. Read generated files directly from disk,
13+
and use `--stdio` as the default mode for any zread command instead of trying
14+
to parse the human TUI.
15+
16+
## On-disk layout (read these directly)
17+
18+
Always run `zread` from the workspace root. After a successful generation:
19+
20+
- `./.zread/wiki/current` — text file containing the active version id
21+
(e.g. `2026-03-12-010203`).
22+
- `./.zread/wiki/versions/<id>/wiki.json` — TOC: `{id, generated_at, language,
23+
pages: [{slug, title, file, section, group, level}]}`.
24+
- `./.zread/wiki/versions/<id>/<file>` — page markdown referenced by `pages[*].file`.
25+
- `./.zread/wiki/drafts/` — in-progress generation; presence means a previous
26+
run did not finish. `drafts/wiki.json` exists once the catalog phase
27+
completed.
28+
- `~/.zread/config.yaml` — global config (LLM provider, language, concurrency).
29+
- `~/.zread/login.json` — presence indicates the user has logged in.
30+
31+
To answer questions about a codebase that already has zread output, read these
32+
files directly with the file tools — do not invoke `zread browse`.
33+
34+
## Commands
35+
36+
| Command | Purpose | Key flags |
37+
|---|---|---|
38+
| `zread generate` | Generate wiki for cwd | `-y/--yes`, `--draft resume\|clear\|cancel`, `--skip-failed`, `--stdio` |
39+
| `zread browse` | Serve docs at http://localhost:9681+ and open browser | `--generate`, `--version <id>`, `--host`, `--port`, `--stdio` |
40+
| `zread login` | OAuth into BigModel/Z.AI to obtain an API key | `--custom`, `--model`, `--stdio` |
41+
| `zread config` | Edit `~/.zread/config.yaml` | `--stdio` |
42+
| `zread update` | Self-update CLI | `--stdio` |
43+
| `zread version` | Print version | `--stdio` |
44+
45+
`--stdio` is supported on every command and turns the process into a JSON-line
46+
machine protocol on stdin/stdout. See
47+
[references/stdio-protocol.md](./references/stdio-protocol.md) for the wire
48+
format (events, `waiting_for`, `done`, `quit`). Load it whenever zread is
49+
invoked from another program/agent.
50+
51+
## Decision tree for an AI agent
52+
53+
1. **User wants to read existing wiki content?**
54+
- Check `./.zread/wiki/current`. If present, read `wiki.json` and the page
55+
markdown directly. No CLI invocation needed.
56+
- For known *public* GitHub repos, prefer the `mcp__zread__*` tools
57+
(`get_repo_structure`, `read_file`, `search_doc`) over running the CLI.
58+
59+
2. **User wants to (re)generate docs?**
60+
- Confirm with the user first — `generate` is long-running, calls an LLM,
61+
and writes files. Get explicit consent in unfamiliar directories.
62+
- Verify `~/.zread/login.json` exists or `~/.zread/config.yaml` has an
63+
`llm.api_key`. If neither, run `zread login` first.
64+
- If `./.zread/wiki/drafts/` exists, decide:
65+
- resume previous run → `zread generate --draft resume -y`
66+
- throw away and start fresh → `zread generate --draft clear -y`
67+
- Otherwise: `zread generate -y`.
68+
- To not block on a few failing pages: add `--skip-failed`.
69+
70+
3. **User wants to view docs in a browser?**
71+
- `zread browse` (add `--generate` to bootstrap if no wiki exists yet).
72+
73+
4. **User wants to script zread / consume output programmatically?**
74+
- Use `--stdio` and follow stdio-protocol.md. Do not screen-scrape the TUI.
75+
76+
## Non-interactive invocation rules
77+
78+
- Always pass `-y` to `generate` when running unattended; otherwise it stops
79+
at a catalog confirmation gate.
80+
- Always set `--draft` explicitly when a draft may exist, so the command does
81+
not prompt.
82+
- For any command run from another agent/script, use `--stdio` so output is
83+
parseable JSON instead of ANSI TUI frames.
84+
- `zread` writes logs to `~/.zread/log/zread.log` — read this if a run fails
85+
silently.
86+
87+
## Safety / blast radius
88+
89+
- `generate` consumes LLM tokens (real cost) and can run for many minutes on
90+
large repos. Confirm before launching.
91+
- `generate` writes only under `./.zread/` and does not commit anything to
92+
git. It is safe to delete `./.zread/wiki/drafts/` to recover from a stuck
93+
state.
94+
- `update` replaces the zread binary in place and is hard to reverse — only
95+
run it when the user explicitly asks.
96+
- `login` opens a browser for OAuth; do not run it in a non-interactive
97+
context unless the user has asked for it.
98+
99+
## Reference files
100+
101+
- [references/stdio-protocol.md](./references/stdio-protocol.md) — JSON-line
102+
wire protocol shared by every command's `--stdio` mode. Load when
103+
programmatically driving zread.

‎references/stdio-protocol.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# zread `--stdio` protocol
2+
3+
Every zread command accepts `--stdio`, switching the process from an interactive
4+
TUI into a JSON-line machine protocol on stdin/stdout. This is the contract used
5+
by GUI / programmatic clients to drive zread.
6+
7+
## Architecture
8+
9+
zread internally uses a Driver / Client split:
10+
11+
- **Driver** holds all business logic (loading config, calling LLMs, running the
12+
doc server, managing drafts). It is framework-agnostic and only talks to a
13+
`Transport`.
14+
- **Client** is either a Bubbletea TUI or `StdioClient`. With `--stdio`, the
15+
cobra command instantiates `transport.NewLocalTransport()` (a channel pair),
16+
spawns the driver in a goroutine, then runs `transport.NewStdioClient(clientT).Run(ctx)`.
17+
- `StdioClient` reads JSON lines from `os.Stdin` and forwards them as commands
18+
to the driver, while encoding `Event`s from the driver to `os.Stdout` (one
19+
JSON object per line). It returns when an event with `"done": true` is
20+
received.
21+
22+
Result: stdin = command stream, stdout = event stream, both newline-delimited
23+
JSON. stderr is reserved for logs/errors and should not be parsed.
24+
25+
## Event format (driver → client, stdout)
26+
27+
```json
28+
{
29+
"vm": { ... }, // current ViewModel snapshot (shape per-command)
30+
"waiting_for": ["..."], // command types accepted in the current state
31+
"done": false, // true on the final event; client should exit
32+
"error": "" // non-empty when the previous command was rejected
33+
}
34+
```
35+
36+
- An event is emitted after every state transition. The client should treat
37+
`vm` as the full state (no diffs).
38+
- `waiting_for` enumerates the legal `type` values the client may send right
39+
now. `quit` is always implicitly accepted.
40+
- The very last event always has `"done": true` and an empty `waiting_for`.
41+
42+
## Command format (client → driver, stdin)
43+
44+
One JSON object per line:
45+
46+
```json
47+
{"type": "<command_type>", "params": { ... }}
48+
```
49+
50+
- `type` is required. `params` may be omitted (treated as `{}`).
51+
- Universal command: `{"type":"quit","params":{}}` — every driver handles it
52+
and shuts down cleanly.
53+
- Command types prefixed with `_` are driver-internal (async results injected
54+
by the driver itself) and must never appear in `waiting_for`; clients should
55+
not send them.
56+
- Sending a command not in `waiting_for` produces an event with `error` set
57+
while `vm`/`waiting_for` remain unchanged.
58+
59+
## Driving a session
60+
61+
1. Spawn `zread <command> --stdio` with piped stdin/stdout.
62+
2. Read the first event — it carries the initial ViewModel and `waiting_for`.
63+
3. Render or inspect `vm`; pick a legal command from `waiting_for` and write it
64+
as a single JSON line followed by `\n`.
65+
4. Loop: read next event, react, write next command.
66+
5. Stop when an event arrives with `"done": true`. The process will exit on
67+
its own; no further input is required. Sending `quit` at any time triggers
68+
the same shutdown path.
69+
70+
## Per-command notes
71+
72+
The `vm` schema, state machine, and command vocabulary are defined per command
73+
in `pkg/ui/<command>/viewmodel.go` and `driver.go` in the zread_cli repo. The
74+
common ones:
75+
76+
- `zread browse --stdio` — emits loading → serving (with server URL in `vm`),
77+
or `select_version` when multiple wikis exist. Commands include
78+
`select_version` (`{"wiki_id":"..."}`) and `quit`.
79+
- `zread generate --stdio` — emits catalog progress, an optional
80+
`catalog_confirm` gate, then per-page progress. Commands include
81+
`confirm_catalog`, `retry`, `skip`, `quit`. `--yes` skips the confirm gate.
82+
- `zread config --stdio`, `zread login --stdio`, `zread update --stdio`,
83+
`zread version --stdio` follow the same envelope; consult the matching
84+
driver for their `waiting_for` values.
85+
86+
## Practical tips
87+
88+
- Always flush stdin after writing a command (the driver reads line-by-line).
89+
- Treat any line on stdout that fails to parse as JSON as a bug — log it but
90+
do not crash; zread should not print non-JSON to stdout in `--stdio` mode.
91+
- For long-running commands (`generate`), keep reading events continuously;
92+
there is no heartbeat, but progress events arrive whenever state changes.
93+
- To cancel cleanly, send `{"type":"quit","params":{}}` and then drain events
94+
until `done` rather than killing the process.

0 commit comments

Comments
 (0)