github-agent#

GitHub repository and wiki steward for AI agents: audits README, CHANGELOG and community health, renders the banner and social preview, builds and publishes the wiki, checks links, anchors and topics — one command per job. Python 3, standard library only.

<img src="https://github.com/paulmann/github-agent/raw/main/assets/social-preview.png" alt="github-agent — repository and wiki steward for AI agents" width="100%">

Installation · Usage · Images · Wiki · AGENTS.md · Changelog · Issues · Security · Русская версия

A repository rarely fails on code; it fails on documentation. The README has no installation
section, the changelog has no dates, the wiki is three pages without navigation, the banner is
a broken image, the description is one word. git push succeeds, so the defect lives for years.

This pack puts a verifiable contract on each of those places and reduces the work to one
command. It does not write marketing copy and does not invent numbers: it checks what a human
wrote and refuses to publish what is broken.

Documentation status. Every number in this README was measured on 2026-10-24 against
version 1.1.0 with the commands named in the table. Long guides live in the
Wiki and docs/; the protocol for
agents is AGENTS.md.

Contents#

• What the pack does

• In numbers

• Installation

• Usage

• Checks that run

• Images

• Import into another agent

• Wiki as documentation

• Languages of the documentation

• How it is built

• Limitations

• Development

• Contributing

• License

What the pack does#

Each command prints findings as file:line with a rule id, and returns 0 clean, 1 with
errors, 2 on a usage problem. An agent therefore does not need to read the tree to learn its
state: one command and one exit code are enough.

In numbers#

Measured in this tree on 2026-10-24:

Installation#

Only Python 3.11+ is required (verified on 3.13.15). No pip install, no build step. Pillow is
optional: with it assets render also produces a PNG, without it the SVG alone.

git clone https://github.com/paulmann/github-agent.git
cd github-agent

python tools/ghagent.py selftest

Installing the skill into an agent copies the pack into the agent's skill root, with a sha256
manifest:

python tools/ghagent.py install --profile autoclaw --write   # AutoClaw2
python tools/ghagent.py install --profile harness  --write   # HARNESS
python tools/ghagent.py install --target <dir>     --write   # SagaAI and anything else

Verification and rollback:

python tools/ghagent.py verify-install --profile autoclaw
python tools/ghagent.py uninstall --profile autoclaw --write

uninstall refuses to delete a directory that has no .install.json: it must not remove what
another tool installed.

Usage#

# 1. state of a local repository (exit 1 means errors)
python tools/ghagent.py audit .

# 2. the same for GitHub metadata
python tools/ghagent.py audit --repo owner/name --http

# 3. documents: BOM, CRLF, headings, tables, links, anchors, table of contents
python tools/ghagent.py doc --root .

# 4. images: render from metadata, then verify size, format and references
python tools/ghagent.py assets render --title "Project" --tagline "What it does." --write
python tools/ghagent.py assets check

# 5. wiki: build, verify, publish (without --push it is a dry run)
python tools/ghagent.py wiki build
python tools/ghagent.py wiki verify
python tools/ghagent.py wiki publish --repo owner/name --push

# 6. changelog
python tools/ghagent.py changelog check
python tools/ghagent.py changelog suggest --since v1.0.0
python tools/ghagent.py changelog release 1.1.0 --write
python tools/ghagent.py changelog notes 1.1.0

# 7. metadata: description and topics
python tools/ghagent.py meta suggest
python tools/ghagent.py meta apply --repo owner/name --description "…" --topics a,b --write

# 8. one combined report
python tools/ghagent.py report . --out AUDIT.md

Example audit output:

[ERROR] repo.contributing        CONTRIBUTING.md is absent  hint: add CONTRIBUTING.md
[WARN ] readme.badges            only 1 badge(s)  hint: 3-8 badges: CI, release, license, runtime
[ERROR] changelog.date-missing   version 1.1.0 has no ISO date  CHANGELOG.md:14
score: 72.5% (22 scored, 1 skipped)

Checks that run#

A rule that examined zero objects is not passed: it is reported as coverage.skipped, and an
empty tree is doc.no-text-files.

Images#

The banner at the top of this file is generated by the pack itself:

python tools/ghagent.py assets render --title "github-agent" \
    --tagline "Repository and wiki steward for AI agents: one command per job." \
    --command "ghagent.py audit ." --chips "python,github,wiki,lint" --write

• assets/social-preview.png — 1280×640, under 1 MB, ready for Settings → Social preview.

• assets/social-preview.svg — vector twin for the README, no dependency needed.

• assets check verifies format, byte size, dimensions, alt text and that every referenced file
  exists. The repository copy is not the social preview automatically: that upload is a manual
  step, and the check prints the reminder.

Import into another agent#

The snippet block names the pack path, the verification command and one rule: one job, one
command. After import the agent must run verify-install and get 0; anything else means the
installed copy is not the tested one. Details: docs/IMPORT.md.

Wiki as documentation#

The wiki is maintained from the repository: pages live in wiki/, order is set by
wiki/wiki.json. wiki build rewrites links for the wiki namespace — internal links lose
.md, links into the repository tree become absolute, and a relative image is an error because
the wiki repository cannot see the project tree.

Built and verified with the pack's own commands. Publication needs one action in the GitHub
interface: <repo>.wiki.git does not exist until a first page is saved, and git push cannot
create it — wiki publish then returns wiki.remote-missing with that step.

Languages of the documentation#

English files are canonical; Russian translations carry the .ru.md suffix, the convention
GitHub itself uses (README.ru.md, AGENTS.ru.md, wiki/01-Why.ru.md).

Translations are updated in the same commit as the original. A translation that silently lags is
a documentation defect, and the wiki carries both sets: English pages as canonical, Russian as
*.ru.md pages in their own navigation group.

How it is built#

flowchart LR
  R["Repository<br/>README, CHANGELOG, docs"] --> A["audit"]
  R --> D["doc"]
  R --> I["assets"]
  W["wiki/ + wiki.json"] --> B["wiki build"]
  B --> V["wiki verify"]
  V --> P["wiki publish --push"]
  A --> O["report, --json"]
  D --> O
  I --> O

Anchors follow GitHub's rules: lowercase, punctuation dropped, spaces to hyphens, a repeated
heading gets -1. The rule was verified against a live table of contents: an em dash in a
heading produces a double hyphen.

Limitations#

• audit --repo and meta need gh or GITHUB_TOKEN. Without them the command returns an
  error instead of an empty success.

• External links are not fetched: relative paths, anchors and structure are checked. A network
  crawl is a separate decision, not a side effect of a linter.

• Wiki pages are barely discoverable through search engines: per GitHub documentation, only
  wikis with 500+ stars and public editing disabled are indexed. Use GitHub Pages for discovery.

• changelog suggest is a draft. It does not know what matters to a user.

• PNG rendering needs Pillow. Without it the SVG is produced and the check says why no PNG
  exists, instead of pretending a social preview is ready.

Development#

python tools/ghagent.py selftest
python tests/run_tests.py
python tools/ghagent.py doc --root .
python tools/ghagent.py audit .
python tools/ghagent.py assets check

A new rule arrives with a fixture that fails without it and a decoy that must stay quiet. A rule
without a fixture is removed: a check that cannot be proven is worse than no check.

Contributing#

Before a pull request: python tests/run_tests.py and python tools/ghagent.py doc --root .
must be green. One change, one reason. Rules: CONTRIBUTING.md, security
policy: SECURITY.md.

License#

MIT.