project-docs — Claude Code Skill

English · Deutsch

Example: project-docs/index.html from a real project — rendered in the project's own brand (colors, fonts, logo), not as plain markdown.

---

English

The key idea

The documentation is a single, self-contained index.html — not markdown.

• Human-readable. Open it in any browser and it looks like a real product page, styled in the project's brand (logo, colors, fonts, spacing). No build step, no static site generator, no Docusaurus.
• Clean changelog & decisions log. Section markers (<!-- claude:NAME:start --> ... <!-- claude:NAME:end -->) let Claude make surgical edits — no churn, no rewrites, no diff noise. The history actually accumulates instead of being clobbered.
• Portable across AI agent systems. Cursor, Aider, Codex, ChatGPT, Gemini CLI — any agent can read a single HTML file. To share project context with a new tool, you copy one file. No vendor-specific format, no markdown-fragment graph, no embedding store to rebuild.
• Self-contained. CSS + JS inline, < 100KB, images linked from ../public/.... Drop it in a gist, attach it to an issue, mail it to a stakeholder — it just renders.

This skill teaches Claude Code how to read, write, and bootstrap that file. But the file itself is the deliverable; the skill is just the maintenance harness.

How Claude uses it

• READ mode — at the start of every session in a repo with project-docs/, Claude opens the doc first (meta block, file map, decisions, wishlist, glossary) before grepping or planning. This gives Claude oriented context without burning tokens on exploration.
• UPDATE mode — after meaningful work, Claude surgically edits the relevant <!-- claude:NAME:start --> ... <!-- claude:NAME:end --> section, bumps data-updated, and appends a changelog entry. The full file is never rewritten.
• SETUP mode — in a new repo, Claude analyzes the codebase (stack, file map, brand colors, env var names, recent commits) and generates the initial project-docs/ folder.

The doc itself is a single self-contained HTML file (CSS + JS inline, < 100KB, images linked) with six tabs: Overview · Features · Design · Architecture · Wishlist · Changelog.

Install

git clone https://github.com/tomgoeck/project-docs-skill.git ~/.claude/skills/project-docs

That's it. Claude Code auto-discovers skills under ~/.claude/skills/. The description in SKILL.md is strong enough to trigger Claude on its own — it fires at the start of every session in a git repository, when you ask to plan/implement/refactor/ship a feature, or when you mention "the docs" / "die Doku" / "the project page".

Optional: pin it in your global CLAUDE.md

If you want a guaranteed always-on trigger (instead of relying on the skill's auto-discovery heuristics), add this to ~/.claude/CLAUDE.md:

## project-docs skill — always on

At the start of every session where the working directory is a git repository — and again whenever the user asks to plan, implement, refactor, or ship a feature — invoke the `project-docs` skill in **READ mode** before doing anything else:

1. Check whether `project-docs/index.html` exists in the repo root.
2. If yes: read it (especially the `<script id="meta">` block, the File Map, the Decisions Log, the Glossary, and the Wishlist) before searching code or proposing a plan.
3. If no: mention to the user that the project has no `project-docs/` yet and offer to run the skill's SETUP mode.

After completing meaningful work in a repo that has `project-docs/`, switch to the skill's UPDATE mode and write the changes back into the relevant `<!-- claude:NAME:start -->` section via surgical `Edit` calls. Always bump the meta block's `lastUpdated` and the affected card's `data-updated` to today's date.

First-time setup in a repo

Just tell Claude:

Set up project docs for this repo. (or in German: "Dokumentiere dieses Projekt", "Setze die Doku auf")

Claude will follow reference/SETUP.md: analyze the codebase, create project-docs/index.html from the template, copy MAINTENANCE.md and take-screenshots.mjs, and (optionally) wire CLAUDE.md at the repo root.

What's in this repo

project-docs-skill/
├── SKILL.md                       # Skill definition (READ/UPDATE/SETUP modes)
└── reference/
    ├── SETUP.md                   # Step-by-step first-time setup template
    ├── MAINTENANCE.md             # Editing rules (gets copied into target repos)
    ├── index.template.html        # The HTML scaffold
    └── take-screenshots.mjs       # Playwright screenshot helper

License

MIT.

---

Deutsch

Die Kernidee

Die Doku ist eine einzige, in sich geschlossene index.html — kein Markdown.

• Für Menschen lesbar. Im Browser öffnen, sieht aus wie eine echte Produktseite, gestylt im Branding des Projekts (Logo, Farben, Fonts, Spacing). Kein Build-Schritt, kein Static-Site-Generator, kein Docusaurus.
• Sauberes Changelog & Decisions Log. Über Section-Marker (<!-- claude:NAME:start --> ... <!-- claude:NAME:end -->) macht Claude chirurgische Edits — kein Churn, keine Komplett-Rewrites, kein Diff-Rauschen. Die Historie akkumuliert sich wirklich, statt überschrieben zu werden.
• Portabel zwischen KI-Agenten-Systemen. Cursor, Aider, Codex, ChatGPT, Gemini CLI — jeder Agent kann eine einzelne HTML-Datei lesen. Um Projektkontext mit einem neuen Tool zu teilen, kopierst du eine Datei. Kein Vendor-Format, kein Markdown-Fragment-Graph, kein Embedding-Store zum Neuaufbau.
• Self-contained. CSS + JS inline, < 100 KB, Bilder verlinkt aus ../public/.... In einen Gist werfen, an ein Issue hängen, einem Stakeholder mailen — rendert einfach.

Dieser Skill bringt Claude Code bei, wie er diese Datei liest, schreibt und initial anlegt. Aber das eigentliche Artefakt ist die Datei selbst; der Skill ist nur das Wartungs-Geschirr.

Wie Claude sie nutzt

• READ-Modus — am Anfang jeder Session in einem Repo mit project-docs/ öffnet Claude die Doku zuerst (Meta-Block, File Map, Decisions, Wishlist, Glossar), bevor gegrept oder geplant wird. Damit hat Claude ohne Token-Verschwendung Kontext.
• UPDATE-Modus — nach signifikanter Arbeit editiert Claude chirurgisch den passenden <!-- claude:NAME:start --> ... <!-- claude:NAME:end -->-Abschnitt, aktualisiert data-updated und ergänzt einen Changelog-Eintrag. Die Datei wird nie als Ganzes neu geschrieben.
• SETUP-Modus — in einem neuen Repo analysiert Claude die Codebase (Stack, File Map, Brand-Farben, Env-Var-Namen, letzte Commits) und erzeugt den initialen project-docs/-Ordner.

Die Doku selbst ist eine in sich geschlossene HTML-Datei (CSS + JS inline, < 100 KB, Bilder verlinkt) mit sechs Tabs: Overview · Features · Design · Architecture · Wishlist · Changelog.

Installation

git clone https://github.com/tomgoeck/project-docs-skill.git ~/.claude/skills/project-docs

Fertig. Claude Code findet Skills unter ~/.claude/skills/ automatisch. Die description in SKILL.md ist stark genug, dass der Skill von alleine triggert — am Anfang jeder Session in einem Git-Repo, wenn du um Planung/Implementierung/Refactor/Shipping bittest, oder wenn du „the docs" / „die Doku" / „die Projektseite" erwähnst.

Optional: in der globalen CLAUDE.md verdrahten

Wenn du einen garantierten Always-On-Trigger willst (statt dich auf die Auto-Discovery-Heuristik zu verlassen), füge das in deine ~/.claude/CLAUDE.md:

## project-docs skill — always on

Am Anfang jeder Session in einem Git-Repository — und immer wenn ich dich bitte, ein Feature zu planen, zu implementieren, zu refactoren oder zu shippen — rufe den `project-docs`-Skill im **READ-Modus** auf, bevor du irgendetwas anderes tust:

1. Prüfe, ob `project-docs/index.html` im Repo-Root existiert.
2. Falls ja: lies sie (besonders den `<script id="meta">`-Block, die File Map, das Decisions Log, das Glossar und die Wishlist), bevor du Code suchst oder einen Plan vorschlägst.
3. Falls nein: weise mich darauf hin, dass das Projekt noch keine `project-docs/` hat, und biete den SETUP-Modus an.

Nach signifikanter Arbeit in einem Repo mit `project-docs/` wechsle in den UPDATE-Modus und schreibe die Änderungen über chirurgische `Edit`-Calls in den passenden `<!-- claude:NAME:start -->`-Abschnitt zurück. Aktualisiere immer `lastUpdated` im Meta-Block und `data-updated` der betroffenen Card auf das heutige Datum.

Erstes Setup in einem Repo

Sag Claude einfach:

Setze die Doku für dieses Projekt auf. (oder: „Dokumentiere dieses Projekt", „Set up project docs for this repo")

Claude folgt dann reference/SETUP.md: analysiert die Codebase, erstellt project-docs/index.html aus dem Template, kopiert MAINTENANCE.md und take-screenshots.mjs und verdrahtet optional CLAUDE.md im Repo-Root.

Inhalt dieses Repos

project-docs-skill/
├── SKILL.md                       # Skill-Definition (READ-/UPDATE-/SETUP-Modi)
└── reference/
    ├── SETUP.md                   # Schritt-für-Schritt-Setup-Template
    ├── MAINTENANCE.md             # Editierregeln (werden ins Ziel-Repo kopiert)
    ├── index.template.html        # Das HTML-Grundgerüst
    └── take-screenshots.mjs       # Playwright-Screenshot-Helper

Lizenz

MIT.