How The Skill Works

This page describes what the agent does once the skill loads, as skills/wikiwright/SKILL.md lays it out in 0.9.0. The helper's own rules are on What the helper checks.

When it loads

The skill's description tells the agent to use it when you ask to write, fill out, generate, create or update a wiki for a repository or package. Its examples are "write a wiki for this repo", "fill out the GitHub wiki", "update the wiki for 2.4.0" and "the wiki is empty". It also loads when a package-modernize run reaches its wiki step, and for "refresh wikiwright" or "is wikiwright stale". It is not for a README on its own, a docs site such as GitHub Pages or Docusaurus, an Obsidian vault or ai-docs/ notes.

Two modes

A new wiki, where the repository has none or only GitHub's placeholder page, goes through the eight steps below. An update for a release, where the wiki exists and the repository's ai-docs/notes/*-github-wiki.md says how it was made, follows update mode. A draft-only request ("put the pages in ./wiki-draft/, don't push or commit") writes the changed pages to that folder and the notes beside them, and leaves both clones untouched.

The eight steps

0. Freshness and the overlay. The agent reads evergreen.json next to SKILL.md; if the skill is past its research date or a learning contradicted it, it says so in one line and refreshes after the task. Then it reads your private overlay, if you have one (Getting started).
1. Preflight. wikiwright.py preflight OWNER/REPO --enable --clone <clone>.wiki checks the wiki feature, whether the .wiki.git repository exists, and whether it holds only the placeholder. It runs first, before any writing, even when your overlay already lists the wiki.
2. Survey. The agent reads the README, CHANGELOG, AGENTS.md and CLAUDE.md, ai-docs/, the public source, the tests and the CI workflows. From GitHub it reads releases, tags, and issues and pull requests, open and closed; their questions become FAQ entries. From the registry, starting with wikiwright.py registry, it takes versions with dates, downloads, the published package's files and its dependency tree. The agent keeps two lists from here on: facts the README does not state, and places where the shipped docs are wrong.
3. Page set. It picks the pages for the repository's kind (see Page sets).
4. Verify every example. It installs the published version into a scratch folder, never the working tree, and runs every example the pages will show from a verification script started with wikiwright.py scaffold. Packages that make requests are answered by a local fixture server or stand-in proxy, never the internet. The script and its output are saved so the next release can run them again and diff.
5. Write the pages. File names are hyphenated, headings are in sentence case and links are [Text](Page-Name). Input and output sit in paired blocks with real output only, and "not tested" marks whatever did not run. Pages use LF line endings and carry no AI attribution, and the footer names the version and the date.
6. Check. The agent rereads every sentence asking which output, source line or registry answer supports it, then runs check, outputs, snippets and the everwrite prose checker when it is installed. Each must pass.
7. Publish. It commits in the wiki working copy and pushes to master, then runs wikiwright.py live until every page answers.
8. Record. It writes ai-docs/notes/<date>-github-wiki.md in the repository from the note template: the pages, how they were verified, the facts found, the numbered inaccuracies in the shipped docs and the update procedure. It does not edit your README or CHANGELOG unless asked; it lists their mistakes for you.

Update mode

1. Read the wiki note and git pull --ff-only the wiki working copy.
2. Read the CHANGELOG since the version the footer names, and survey the new version on the registry.
3. Run the saved verification script against the new published version and compare: wikiwright.py diffout <saved output> <new output> lists every changed, added and removed section, and wikiwright.py outputs lists every page output the new run no longer prints. Recipes that import other packages are run against their current versions too, since a clean diff proves only the cases the script already holds.
4. Update the pages that name the version, Versions and upgrading, and the footer.
5. Check, publish and record as in steps 6 to 8.

A wiki written before its script was saved is adopted first: the agent writes or completes the program until every page output appears in its saved output.

Page sets

The pages depend on what the repository is. The sets in references/page-sets.md and references/page-sets-cli.md were each tested on real wikis:

Kind	Pages
Library (npm or NuGet)	Home, Getting started, API reference, a behaviour page named for what it does (such as How-Titles-Are-Chosen), edge cases and errors, Recipes, Versions and upgrading, FAQ, Development
Library with a command line	the library set plus Commands
Seeded or deterministic output	adds a behaviour page named after the promise (such as Same-Seed-Same-Sequence)
Command-line tool	Home, Getting started, Commands, Configuration, Recipes, Versions and upgrading, FAQ, Development
Library and its tool in one repository	both sets together

Applications, websites and monorepos have no tested set yet. The agent says so; for an application it starts from Home, Getting started, Configuration, Architecture, Deploying, FAQ and Development, and records what the run taught it. On Gitea, Forgejo, GitLab and Azure DevOps the set stays the same and the navigation files and names change.

What it asks of you

GitHub creates a wiki's repository only when someone saves a first page in the web UI. Switching the wiki feature on does not create it, and no API can. When preflight reports no-wiki-repo, the agent asks you in its first message to open https://github.com/OWNER/REPO/wiki/_new and save any text, and carries on with the survey, the verification and the pages meanwhile. The push replaces that page.

The agent also stops for your approval wherever your tools require it, which in Claude Code can include the push itself.

What it never does

• Request the real service a package talks to, even once to record an answer. Output that is remote content is shown from a local stand-in and labelled as sample content.
• Show an output it did not produce, or convert one by hand into another layout.
• Overwrite a wiki that already has pages: has-pages means read every page and update in place.
• Add AI attribution to pages or commits.
• Edit the README or CHANGELOG without being asked.

Learnings while it works

When you correct the agent, an error repeats, or it finds a workaround or an environment fact, it writes a lesson to the skill's LEARNINGS.md with an ID and a short code name. The skill was built from twelve real wikis written between 2026-09-28 and 2026-09-30, listed in references/page-sets.md.

With package-modernize

A package-modernize run reaches the wiki in its Phase 7, after the release is verified on the registry. An existing wiki takes update mode; the golden recordings of old versions that package-modernize keeps feed Versions and upgrading.