Zread Skill

This repository contains a skill for zread, a CLI that generates wiki-style documentation for code repositories.

The skill is meant for one job: help an agent understand an unfamiliar codebase through zread output instead of re-reading the entire repository file by file.

Installation

1. Install the zread CLI

Install zread first. There are two supported installation methods:

npm install -g zread_cli

or

brew tap ZreadAI/homebrew-tap
brew install zread

Then verify the installation:

zread version

2. Install this skill

Ask your AI agent to install the skill from GitHub:

install this skill https://github.com/ZreadAI/zread-skill

If you prefer to install it manually, copy this directory into your local skills directory:

Example:

cp -R zread ~/.claude/skills/zread

Your final layout should look like this:

/zread/
  SKILL.md
  README.md
  references/
    stdio-protocol.md

Once the folder is in place, an agent that supports SKILL.md-based skills can load and use it.

Features

• Read existing ./.zread/wiki/ output instead of crawling source files again
• Guide an agent to run zread generate safely when documentation does not exist yet
• Use --stdio as the default mode for agent automation, instead of parsing the interactive TUI
• Explain the role of current, versions, and drafts in zread output
• Include a reference for the zread --stdio JSON-line protocol

When To Use

Use this skill when you want to:

• understand an unfamiliar repository quickly
• read an existing zread-generated wiki
• generate a repository overview or project wiki
• serve docs locally with zread browse
• drive zread programmatically from a script or agent

How It Works

The skill follows a simple workflow:

1. If ./.zread/wiki/current exists, read the generated wiki files directly.
2. If no wiki exists, run zread generate only when the user wants docs to be generated.
3. Before generation, confirm with the user because generation consumes LLM tokens and writes under ./.zread/.
4. In automated workflows, use --stdio.

Repository Layout

• SKILL.md: the skill definition, trigger conditions, and operating rules
• references/stdio-protocol.md: the zread --stdio machine protocol
• appmap.log: local artifact, not part of the skill itself

zread Output

After a successful generation, zread typically writes:

• ./.zread/wiki/current: the active wiki version id
• ./.zread/wiki/versions//wiki.json: the generated page index
• ./.zread/wiki/versions//: the actual markdown pages
• ./.zread/wiki/drafts/: unfinished generation state

If you need to integrate with zread programmatically, see references/stdio-protocol.md.