git-wiki

Files (2)

• SKILL.md
• export-wiki-bundle.mjs · scripts/

SKILL.md (first lines)

# Project Wiki

Maintain local wikis for a code project under `.wiki` by default, with optional language-specific roots such as `.wiki-cn`, `.wiki-fr`, or an exact user-named wiki directory such as `wiki-cn`.

Source of truth is always the current git-tracked repository files at `HEAD`, including tracked documentation in `.docs/` and `docs/`, not the wiki.
The wiki files themselves may be untracked; read and update the live selected wiki root from the working tree when present.

## Rules

* Operate only on git-tracked files and git history
* Ignore staged and unstaged uncommitted changes; ingest and query verification use committed content at `HEAD` only
* Select exactly one wiki root per request. Use `.wiki` by default; use the explicit root or language the user names, such as `.wiki-cn`, `wiki-cn`, `.wiki-fr`, "Chinese wiki", or "French wiki"
* Each wiki root is independent. Do not sync, compare, translate, merge, or copy pages between language roots unless the user explicitly asks
* Exclude all wiki roots from git-based source selection: `.wiki/**`, `.wiki-*/**`, and `wiki-*/**`
* Do not assume any wiki root is git-tracked; use the selected root's current `index.md` checkpoint when it exists
* Every wiki page must have YAML frontmatter
* The selected root's `index.md` must be updated on every ingest
* Do not ask the user before ingesting
* Export reads the live working-tree files under the selected wiki root, not the git-tracked repository at `HEAD`

## Wiki Layout

Required:

* `<wiki-root>/index.md` — human entry point and master catalog (tracks last ingest commit for that root only)

Optional (create as needed):

* `<wiki-root>/overview/` — orientation pages that explain the project, startup path, storage, and reading path
* `<wiki-root>/features/` — one page per significant product capability or implementation area
* `<wiki-root>/bug-fixes/` — one page per notable bug fix or patch
* `<wiki-root>/concepts/` — cross-cutting ideas and patterns
* `<wiki-root>/entities/` — data models, schemas, types
* `<wiki-root>/flows/` — sequences, pipelines, request lifecycles
* `<wiki-root>/risks/` — invariants, compatibility contracts, fragile behavior, and things not to break
* `<wiki-root>/reference/` — code-shaped reference pages when a source path needs focused explanation
* `<wiki-root>/notes/` — ad-hoc or open questions

### Human understanding structure

The wiki is for a human to understand the codebase, not for the repository to describe itself. Organize the front door around the reader's questions before the code's folders.

`<wiki-root>/index.md` must answer these questions, in this order:

1. What is this?
2. Get started
3. Why does it exist?
4. What happens when I run it?
5. Where is data saved?
6. What are the important moving parts?
7. What should I avoid breaking?
8. Where do I look first?

Use these questions as the primary navigation. `features/`, `entities/`, `flows/`, and `reference/` are supporting evidence, not the first mental model.

The `Get Started` section is for codebase orientation, not a duplicate README. It should give a smart newcomer the first 10 minutes:

* the main command to run
* required environment or services
* expected successful output
* the first files to read
* one safe first change
* one tempting dangerous change

When a repo already has setup instructions in `README.md` or `docs/`, link to them and summarize only what helps the reader understand the code.

### Wiki root selection

* Default wiki root: `.wiki`
* Language-specific roots: prefer `.wiki-<language-code>` when creating a new language wiki, for example `.wiki-cn` for Chinese and `.wiki-fr` for French
* If the user names an exact directory, such as `wiki-cn`, use that exact root instead of normalizing it
* Language roots do not inherit checkpoints, pages, links, or stale status from each other
* When the user asks for a language wiki by language name, write page prose in that language and keep code identifiers, file paths, and API names unchanged

## Page Conventions

### index.md frontmatter

`index.md` carries extra fields to track ingest state:

```yaml
---
title: "Project Wiki"
type: "index"
status: "active"
language: "<language-code|default>"
last_commit: "<full-sha>"
updated_at: "YYYY-MM-DD"
---
```

`last_commit` is the full git commit SHA at the time of the most recent full-repository ingest for the selected wiki root. This checkpoint lives in the selected root's current `index.md` file whether or not that root is git-tracked. On the next ingest for the same root, prefer this saved `last_commit` to find changed files with `git diff --name-status -M <last_commit> HEAD`.

If git metadata is unavailable, do not fall back to filesystem scanning. Ingest and lint are unavailable until git access works again.

### Other pages

```yaml
---
title: "Page Title"
type: "overview|feature|bug-fix|concept|entity|flow|risk|reference|note"
status: "draft|active|stale"
language: "<language-code|default>"
source_paths: []
updated_at: "YYYY-MM-DD"
---
```

Set `language` to `default` for `.wiki`, `cn` for `.wiki-cn` or `wiki-cn`, `fr` for `.wiki-fr`, and the matching language code for other language-specific roots.

Use `status: "stale"` when the source file has changed significantly since the page was last updated, or when the page describes something that no longer exists. During ingest, pages whose `source_paths` changed since `last_commit` should be updated or marked stale. Do not delete stale pages automatically — mark them and note the drift so the user can decide.

### Page naming

* Use lowercase, hyphenated filenames: `auth-middleware.md`, `user-schema.md`
* Name pages for the human idea first: `login-check.md`, `saved-data-shape.md`, `startup-flow.md`
* Use source-path names only for reference pages or when there is no clearer reader-facing name: `src/api/routes.ts` → `<wiki-root>/reference/src-api-routes.md`
* Use descriptive names for concepts and flows: `<wiki-root>/concepts/request-lifecycle.md`

From yysun/awesome-agent-world, MIT.

More from yysun/awesome-agent-world