code-wiki skill

Code Wiki Skill

Generate a full wiki for any codebase — overview, architecture, per-module deep-dives, Mermaid class and sequence diagrams. Inspired by Google CodeWiki, but works on local repos, private repos, and any language. Uses only existing Hermes tools (terminal, readfile, searchfiles, write_file); no Docker, no external services, no extra dependencies.

This skill produces reference documentation (what/how). It does not produce strategic narrative (why — that's a different skill).

When to Use

• User says "document this codebase", "generate a wiki", "make architecture diagrams"
• Onboarding to an unfamiliar repo and wants a structured reference
• User points at a GitHub URL and asks for documentation
• Need a stable artifact (markdown + Mermaid) that renders on GitHub

Do NOT use this for:

• Single-file or single-function documentation — just answer directly
• API reference for one specific endpoint — use read_file and answer inline
• Strategic "why does this exist" narrative — different skill, different purpose
• Codebases the user is actively developing in this session — just answer questions as they come

Prerequisites

• No env vars required.
• git on PATH for repo SHA tracking and remote clones.
• Optional: pygount for language-breakdown stats (see the codebase-inspection skill).

How to Run

Invoke through the terminal tool from the target repo's root, then use readfile / searchfiles / write_file to produce the wiki. Default output location is ~/.hermes/wikis//. Only write into the repo (docs/wiki/) when the user explicitly requests it.

Quick Reference

Procedure

1. Resolve the target

For a GitHub URL:

WIKI_TMP=$(mktemp -d)
git clone --depth 50 <url> "$WIKI_TMP/repo"
cd "$WIKI_TMP/repo"
REPO_SHA=$(git rev-parse HEAD)
REPO_NAME=$(basename <url> .git)

For a local path (or cwd if none given):

cd <path>
REPO_SHA=$(git rev-parse HEAD 2>/dev/null || echo "uncommitted")
REPO_NAME=$(basename "$PWD")

Then set the output dir:

OUTPUT_DIR="$HOME/.hermes/wikis/$REPO_NAME"
mkdir -p "$OUTPUT_DIR/modules" "$OUTPUT_DIR/diagrams"

2. Scan repo structure

Use the terminal tool for the shell work, read_file for manifests:

# Shallow tree first
ls -la

# Deeper tree, noise filtered
find . -type d \
  -not -path '*/\.*' \
  -not -path '*/node_modules*' \
  -not -path '*/venv*' \
  -not -path '*/__pycache__*' \
  -not -path '*/dist*' \
  -not -path '*/build*' \
  -not -path '*/target*' \
  -maxdepth 3 | sort

# Language breakdown (skip if pygount unavailable)
pygount --format=summary \
  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,target" \
  . 2>/dev/null || true

Then readfile the relevant manifests (package.json, pyproject.toml, setup.py, Cargo.toml, go.mod, pom.xml, build.gradle) and the project README. Use searchfiles target='files' to find them rather than guessing names.

3. Pick modules to document

Cap initial pass at 8–10 modules. Heuristics by language:

• Python: top-level packages (dirs with init.py), plus subsystem dirs
• JS/TS: src/, top-level workspace dirs
• Rust: each crate in a workspace, or top-level src/ dirs
• Go: each top-level package directory
• Mixed/unfamiliar: top-level directories that contain source code (not config, not tests)

For very large repos, prioritize by:

1. Imported-from count (a module imported by many is core)
2. LOC (bigger modules usually warrant their own doc)
3. Mentions in README / top-level docs

State the module list to the user before generating per-module docs on big repos — gives them a chance to redirect.

4. Write README.md

readfile the actual project README plus the top 2–3 entry-point files. Then writefile:

# <Project Name>

<One paragraph: what it is and what it's for. Self-contained — don't assume the
reader has the source README.>

## Key Concepts

- **<Concept 1>** — <one line>
- **<Concept 2>** — <one line>

## Entry Points

- [`path/to/main.py`](<link>) — <what runs when you start it>
- [`path/to/cli.py`](<link>) — <CLI surface>

## High-Level Architecture

<2-3 sentences. Detail goes in architecture.md.>

See [architecture.md](architecture.md).

## Module Map

| Module | Purpose |
|---|---|
| [`<module>`](modules/<module>.md) | <one-line purpose> |

## Getting Started

See [getting-started.md](getting-started.md).

For link targets in local mode use relative paths. For cloned repos use https://github.com///blob// so links survive future commits.

5. Write architecture.md

# Architecture

<2-3 paragraphs: shape of the system. What talks to what. Where data enters,
where it exits, where state lives.>

## Components

- **<Component>** — <1-2 sentences>. See [`modules/<module>.md`](modules/<module>.md).

## System Diagram

flowchart TD User([User]) --> Entry[Entry Point] Entry --> Core[Core Engine] Core --> StorageA[(Database)] Core --> ExternalAPI{{External API}}

## Data Flow

1. **<Step>** — [`<file>`](<link>)
2. **<Step>** — [`<file>`](<link>)

## Key Design Decisions

- <Anything load-bearing the reader should know>

Mermaid shape semantics:

• [] = component
• [()] = database / storage
• {{}} = external service
• (()) = entry point or terminal
• --> = sync call, -.-> = async/event

Cap at ~20 nodes per diagram. Split into sub-diagrams if larger.

6. Write per-module docs in modules/

For each selected module, inspect its layout with ls, identify 3–5 most important files (by size, by being named core.py / main.py / init.py, by being imported a lot), then readfile those files (use offset / limit to read only what you need; prefer searchfiles for specific symbols).

# Module: `<module>`

<1-2 sentence purpose.>

## Responsibilities

- <bullet>
- <bullet>

## Key Files

- [`<module>/<file>`](<link>) — <what it does>

## Public API

<Functions/classes/constants other code uses. Group related items. Show
signatures, not full implementations.>

## Internal Structure

<How the module is organized internally. State management.>

## Dependencies

- **Used by:** <other modules>
- **Uses:** <other modules + external libs>

## Notable Patterns / Gotchas

- <Anything non-obvious>

7. Write diagrams/class-diagram.md

Pick the 5–10 most important classes/types. read_file them, then write:

# Class Diagram

## Core Types

classDiagram class Agent { +string name +list~Tool~ tools +chat(message) string } class Tool { <> +name string +execute(args) any } Agent --> Tool : uses Tool <|-- TerminalTool Tool <|-- WebTool

## Notes

<Anything the diagram can't express — lifecycle, threading, etc.>

For languages without classes (Go, C, Rust): use the diagram for struct relationships, or skip class-diagram.md and explain it in prose in architecture.md. Don't force-fit.

8. Write diagrams/sequences.md

Pick 2–4 of the most important workflows. Trace each call path through the code (read entry point, follow function calls), then:

# Sequence Diagrams

## Workflow: <Name>

<1 sentence describing what this does and when it runs.>

sequenceDiagram participant User participant CLI participant Agent participant LLM User->>CLI: types message CLI->>Agent: chat(message) Agent->>LLM: API call LLM-->>Agent: response + tool_calls Agent->>Agent: execute tools Agent-->>CLI: final response

### Walkthrough

1. **User input** — [`cli.py:HermesCLI.run_session`](<link>)
2. **Message dispatch** — [`run_agent.py:AIAgent.chat`](<link>)

Don't invent participants. Every box must correspond to a real component the reader can find in the code.

9. Write getting-started.md

# Getting Started

## Prerequisites

<From manifest files + README. Be specific — versions if pinned.>

## Installation

## First Run

## Common Workflows

### <Workflow 1>
<commands>

## Configuration

- `<config-file>` — <what it controls>
- Env var `<VAR>` — <what it controls>

## Where to Go Next

- Architecture: [architecture.md](architecture.md)
- Module reference: [README.md#module-map](README.md#module-map)