Code Wiki

Code Wiki gives coding agents a fast, verifiable way to understand a repository before reading every source file.

It is delivered as two agent skills—there is no standalone application or public CLI:

• build-code-wiki creates short managed headers in source files and a recursive .code-wiki/wiki.json index.
• use-code-wiki guides agents from repository summaries to directories, file headers, and full source only when needed.

Why Code Wiki?

Coding agents often spend substantial context rediscovering what folders and files do. Code Wiki creates a progressive documentation layer:

repository summary
└── directory summary
    └── file summary
        └── 6-line managed header
            └── complete source file

Every indexed file has a SHA-256 content hash. When code changes, the build skill can identify stale documentation and refresh only the affected file and its ancestor directories.

Status

Code Wiki is an early v0.1 implementation. Use it on a branch and review generated source changes before merging them.

The current version supports managed headers for Python, Shell, YAML, JavaScript, TypeScript, Go, Rust, Java, SQL, CSS, and HTML. Binary, generated, minified, oversized, and unsupported files remain index-only.

Requirements

• Git
• Python 3.11
• A coding harness that supports SKILL.md skills, such as Codex or Claude Code

The bundled scripts use only the Python standard library.

Install the skills

Install both skills from GitHub with the Skills CLI:

npx skills add markthebault/code-wiki --skill build-code-wiki
npx skills add markthebault/code-wiki --skill use-code-wiki

Alternatively, copy the folders under skills/ into your harness's skill directory without changing their internal structure.

Use

Invoke the build skill in a Git repository:

Use $build-code-wiki to generate or refresh the Code Wiki for this repository.

It creates:

.code-wiki/wiki.json

and adds a code-wiki:start / code-wiki:end summary and description block to supported source files.

Then use the navigation skill for normal repository work:

Use $use-code-wiki to understand this repository and locate the relevant code.

The navigation skill treats current source as authoritative. It falls back to reading complete files whenever the index is stale or insufficient.

Safety model

• Respects Git ignore rules.
• Excludes common secrets and dependency/build directories.
• Never adds comments to formats that cannot safely contain them.
• Preserves shebangs, encoding declarations, licenses, BOMs, newline styles, permissions, and non-managed bytes.
• Rejects ambiguous or malformed managed markers without editing the file.
• Writes wiki.json atomically and deterministically.
• Does not generate dependency or call graphs.

Repository layout

skills/   Agent skills, scripts, schemas, and header rules
tests/    Standard-library unit and end-to-end tests
doc/      Product specification and implementation ticket

See the product and technical specification for the complete design. The original implementation contract is available in doc/task.md.

Development

Run the complete suite:

python3 -m unittest discover -s tests -v

Compile all bundled scripts:

python3 -m py_compile \
  skills/build-code-wiki/scripts/*.py \
  skills/use-code-wiki/scripts/*.py

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request, and report security issues according to SECURITY.md.

License

MIT