AGENT SKILL

write-docs

Scaffolds, extends, and reconciles a project's `docs/` tree in the TitusKirch docs format — one stack-agnostic convention shared across all repos, ADRs included (append-only records in `docs/99.adr/`). Routes by state — scaffolds when `docs/` is missing, adds to the right section when it exists, reconciles pages when asked (never rewriting prose). Always previews a plan, writing only after confirmation. Use when the user wants to write, add, scaffold, or update documentation, set up docs/, document a feature, record or supersede an architecture decision, or says things like "write the docs", "add a docs page", "document this", "reconcile the docs", "write an ADR", "record this decision", "Doku schreiben", "docs aktualisieren". Also trigger proactively once a feature has cleared review and final approval — when the work is settled, not when implementation ends — to document the shipped result, and offer an ADR when a decision clearly earns one.

License 许可
MIT
所属仓库
TitusKirch/skills
最近更新
2026-11-02
Stars
★ 3
Forks
0

01 前言 Front Matter

name
write-docs
metadata
{ "summary": "Scaffolds, extends and reconciles a project's docs/ tree — ADRs included — in the TitusKirch docs format." }
description
Scaffolds, extends, and reconciles a project's `docs/` tree in the TitusKirch docs format — one stack-agnostic convention shared across all repos, ADRs included (append-only records in `docs/99.adr/`). Routes by state — scaffolds when `docs/` is missing, adds to the right section when it exists, reconciles pages when asked (never rewriting prose). Always previews a plan, writing only after confirmation. Use when the user wants to write, add, scaffold, or update documentation, set up docs/, document a feature, record or supersede an architecture decision, or says things like "write the docs", "add a docs page", "document this", "reconcile the docs", "write an ADR", "record this decision", "Doku schreiben", "docs aktualisieren". Also trigger proactively once a feature has cleared review and final approval — when the work is settled, not when implementation ends — to document the shipped result, and offer an ADR when a decision clearly earns one.
allowed-tools
[ "Read", "Write", "Edit", "Glob", "Grep", "Bash(jq:*)", "Bash(grep:*)", "Bash(git log:*)" ]

02 资源文件 10

03 SKILL.md 正文

write-docs

The TitusKirch docs format — one opinionated, stack-agnostic convention for a project's docs/ tree, the same in every repo (including client projects). This skill owns the convention; the page mechanics live in REFERENCE.md, the skeletons in templates/. Pages are plain Markdown with title + description frontmatter and numeric-prefixed paths — a clean tree any file-based docs generator can render, index, and feed to an LLM.

Portable is the default; a rendered site is an opt-in mode. A repo that publishes its docs/ through a rendering theme sets docs.render in the config, which flips five page rules and nothing else — the render mode. It is declared, never detected, so a repo that has not written the key gets the portable tree above, unchanged.

Opted out? If the repo config sets docs to false, this skill is disabled for the repo — stop immediately (including the proactive trigger) and tell the user docs are turned off in .tituskirch-skills.json. An absent docs block is not disabled — that falls back to defaults/detection. Check .docs == false on the resolved config before any job — and before indexing .docs.*. A missing jq or config exits non-zero too, so a pass is not evidence the config was read.

Jobs — pick by repo state + intent

State / intent Job
docs/ missing scaffold
docs/ exists + "document feature X" route/add
"update / align / migrate / reconcile docs" reconcile

Optional command shortcuts in clients that expose them: write-docs init, write-docs add <topic>, write-docs reconcile. Otherwise infer from state and the request. Always: plan → confirm → apply.

Proactive trigger — don't wait to be asked. Once a feature has passed all its reviews and reached final approval (signed off or merged), engage this skill yourself and run the route/add job for that feature. Trigger on final approval, not on implementation finished — code still facing review is too early, and a feature that gets reworked shouldn't be documented twice. The write still follows plan → confirm → apply. An ADR has its own proactive moment, on its own trigger: when a decision earns one.

What belongs in docs at all

Code says what happens. Docs say why. An agent reads the code, so a page that narrates what the code does is a slower, staler copy of something already open in the editor — and if the code needs narrating, the fix is the code, not a page about it.

Before writing anything, ask what the reader could not recover by reading the source. Exactly three answers survive that test:

Code cannot express Because Goes to
The roads not taken What was rejected, and why, leaves no trace in what shipped adr, concepts
How new work here is done The intended approach for the next change is not a property of the current one conventions, guides
Where to start A repo has no first line; which seam to enter by, and how the parts relate, is not in a file concepts, getting-started

Everything else — what a function does, which options exist, what a command prints — either belongs in the code and its own reference output, or is already in a file that owns it. If a planned page fits none of the three rows, that is the answer: don't write it.

Routing matrix — what you changed → page type → section

You added / changed Page type Section
A user-facing capability's usage guide / tutorial guides
A repeatable task / "add a new X" how-to (ends w/checklist) guides
A subsystem, model, or how-it-works concept / architecture concepts
A lookup value: env var, CLI flag, config, API reference entry reference
Setup / install / first-run change (update existing) getting-started
A run / deploy / maintain procedure how-to or concept operations
A project-specific rule or pattern concept conventions
An architectural decision + its reasoning ADR (own schema) adr
An explanatory image or requested terminal demo media in the owning page existing section; artifacts in _assets/

A real feature usually spans several types: how-it-works (concepts) + usage (guides) + lookup values (reference). "How it works" means the shape and the reasoning — the seams, the invariants, why it is built this way — never a walk through the implementation, which the code states better and keeps current for free.

The reference row is the one to challenge. Lookup values earn a page only where nothing machine-readable already holds them — an HTTP API with no published schema, env vars with no .env.example. Where a schema, a manifest or --help is the real answer, the reference page is one sentence naming it plus whatever it cannot say (which values are safe to change, which combinations conflict). A transcribed option table is the single most common stale page in any repo. Lead with how-it-works and how-to-use; push every lookup value to reference and link to it. Page type is implied by section + template — it is not a frontmatter field. Catalogue, core sections and presets: REFERENCE.md.

ADRs are the standing exception. They live in docs/99.adr/ (fixed prefix, flat), are named NNNN-title.md — a permanent decision id plus an imperative verb phrase — carry status + date on top of the house frontmatter, run Context / Decision / Consequences (Nygard) with an optional Alternatives considered, and are append-only — a reversed decision writes a new ADR and marks the old one superseded, never edits it; a decision that still stands but whose reasoning has been overtaken grows a dated addendum under its own ## Amendments, the one thing an accepted record may gain in place. A concept page explains how a thing works today; an ADR records why it was chosen, then. Full contract: REFERENCE.md.

Media follows its own contract. Use docs/_assets/ for documentation captures, reuse artifacts shared with a README, and prefer Mermaid for diffable diagrams. For a requested terminal capture, optionally call vhs-demo with the page, docs context and output path; its absence leaves an explicitly outstanding capture. The writer owns inclusion/layout and the capture skill owns production/verification.

When a decision earns an ADR

The matrix above says where a decision goes; this says whether there is one to record. Ask it before routing — the adr row is the only one whose page cannot be pruned later, because the log is append-only.

The threshold. A decision earns an ADR when it constrains work that comes later and its reasoning would otherwise be lost: a choice between real alternatives, a convention every part of the project has to follow, a trade-off that looks like a mistake until the reason is known. Both halves have to hold — a constraint whose reason is obvious from the code needs no record, and a well-argued call that binds nothing later is a comment, not an ADR.

Decisions that typically clear it: architectural shape · integration patterns between parts · technology choices carrying lock-in · boundary and scope decisions · deliberate deviations from the obvious path · constraints invisible in the code · alternatives rejected for non-obvious reasons. A list of the usual suspects, not a checklist — the threshold above is what decides.

Three signs of a certain ADR — hard to reverse, surprising without context, the result of a real trade-off. All three together are sufficient: write the record, no further argument needed. They are never necessary — the cheapest convention in the repo still earns an ADR if it binds later work and its reason would otherwise be lost, and gating on reversal cost alone would exclude exactly the decisions that are easiest to break by accident.

Size is not the gate, and never a reason to skip one. An ADR can be a single paragraph. The value is in recording that a decision was made and why — not in filling out sections. The required H2s stay, and any of them may be one sentence (contract).

What may go in it is the separate question — and the one append-only makes permanent. No sentence in an accepted record can be corrected, so every sentence has to still be true years from now. That rules out the state of the world (currently, is being, a version, a claim about what some tickets hold), anything transcribed out of a file, and any enumeration a later change will extend. Context carries the constraint that forced the decision, not an inventory of the project; a consequence that prescribes how future work is done is a convention and belongs in conventions/, where it can be edited. Freezing a fact deliberately is fine — write it in the past tense. The full test: REFERENCE.md.

Offer an ADR proactively once a decision clearly clears the threshold — same shape as the proactive trigger above: propose the record, plan → confirm → apply, and never write one unasked. Clearly is the bar; a borderline call is the human's to make, so name it and let them answer.

Scaffold — docs/ is missing

  1. Resolve the preset — docs.preset config → detect from the repo (bin/CLI → cli, a published manifest — library, module, agent/skill set → package, a UI app → app, a server entrypoint with no frontend build → service, IaC → infra) → ask. The preset is the whole set of sections to scaffold; none is implicit. Several signals hit at once in most repos — a CLI that also publishes a library, a module shipping a demo app — so resolve by how the thing is primarily consumed, not by what the repo contains: invoked → cli, imported into another project → package, run and used → app/service, applied to an environment → infra. Genuinely co-equal → ask.
  2. Resolve the language, then the locales — docs.language → root language → existing docs/repo language → en (see REFERENCE.md#config). That is also the tree's default locale, living at the source root with no folder of its own. docs.locales names the additional ones, each a folder inside the source (docs/de-DE/); absent means single-locale, exactly as before (Locales). When set, docs.instructions shapes the generated-docs wording (tone, house conventions) — additive only, never overriding the docs format or guardrails.
  3. Resolve the render mode — docs.render, or portable. Read the key; never infer it from a dependency or a config file, and never offer to write it — a repo states its own rendering target, and detection reads the tree that most needs the mode as the one that needs it least. Portable is the answer whenever the key is absent.
  4. Plan the tree — the preset's sections, plus any its conditional column earns here; show it.
  5. Drop any section that would only redirect. For each planned section ask: does this repo have a page's worth of material that is not already canonical somewhere else — a README that covers install and first run, a committed schema that is the config reference, per-module docs that ship with their module? If not, the section's index.md can only say "the real thing is over there", which costs a click and returns nothing. Leave it out, name it in the plan with the reason, and let route/add create it later when it has a page of its own. This applies to every section the preset names — a preset is the starting set, not an obligation.
  6. On confirm — create numeric-prefixed section dirs, each with an index.md (frontmatter title + description, plain-text H1), plus a docs/index.md landing page. Generated docs are emoji-free. Skeletons: templates/, with the render mode's flips applied on copy where it is on. Then, for every locale docs.locales lists, write the same tree translated under docs/<locale>/ — same paths, same numeric prefixes, same slugs, with only title, description and body prose in that language.

A scaffold that produces one section is a success, not a failure — the tree's job is to hold what has no other home, and in a repo whose parts already document themselves that can be a single section. Numbering starts at 1. over whatever survives, so nothing looks missing.

Route / add — docs/ exists

  1. Run the routing matrix; list every page to create or touch.
  2. New page → next free N.kebab.md in the section, frontmatter title + description, body from the matching template, then link it from that section's index.md. Under the render mode the same step drops the body H1, writes an absolute doc path, and leaves the section index to its page-cards component rather than gaining a bullet.
  3. How-tos end with a checklist. Add a > [!NOTE] Status callout (see REFERENCE.md#status-marker) if the feature isn't shipped yet — the render mode writes that marker as its own callout component instead, because the blockquote form does not render there at all.
  4. Delta principle — don't restate what something else already documents; link it, and write the project-specific delta plus the glue. Three sources outrank a page here, in descending order of how badly a copy hurts:
    • A file in this repo. package.json's scripts, a workflow, a schema, a lockfile, a config — a doc that lists their contents is wrong the moment the file changes, and nothing will tell you. Name the file and what is surprising about it; never transcribe values, versions or option tables out of it.
    • Anything the repo ships. A library, plugin or skill travels without docs/, so it must carry its own reference — a second copy here is the one guaranteed to drift.
    • An authoritative upstream source — framework docs, a dependency's README, a standard. A strong guideline, not a hard block: cross-cutting glue, and the reason a thing is set the way it is, are exactly what no source file states.
  5. Updating an existing topic — the one-topic-per-page rule means there's usually exactly one page; grep docs/ for the term, edit it in place, never open a second page on the same topic, and update affected reference tables + cross-links. Never for an ADR — a changed decision is a new ADR that supersedes the old one, and the ADR section's index.md decision log gets the row in the same change.
  6. Verify every fact against current code before writing.
  7. Every listed locale gets the same page change, in the same plan. A page created or edited in the default tree is written to docs/<locale>/ at the identical path for each locale docs.locales names — the section index.md link included. One change, every tree: leaving the translation for later is what puts them out of step, and the locale contract is that they never are. Translate alt text/captions and visible Mermaid labels; preserve shared media references or verified localized variants and report missing required captures. Never copy or generate media in a translation sweep. With docs.locales absent this step does not exist.

Reconcile — align existing docs to the convention

Desired-state, idempotent — like a --fix linter for the docs tree.

  1. Read the whole docs/ tree fresh (it is live state — never cached).
  2. Resolve the render mode before diffing anything — it decides which convention the tree is being measured against, and two of the mechanical fixes below are destructive under the wrong one: they would strip the theme's frontmatter fields off the pages that need them and rewrite the mode's absolute doc paths into dangling relative ones.
  3. Diff against the convention and group the plan:
    • Auto-fix (mechanical) — numbering gaps/dupes, missing index.md, removed/unknown frontmatter keys, N.kebab.md filename normalization, unambiguous broken links.
    • Prompt (value-needing) — a missing required field (title/description): derive a candidate from the H1 / first paragraph and confirm.
    • Import (value-needing) — a dedicated ADR directory outside 99.adr/ (docs/adr/ and near variants): decisions recorded in someone else's format, which every other category misses, so they are missing from the decision log while the log still reads as complete. Measure each file against the threshold first — it governs an adopted record exactly as it governs a written one, and this is the last moment it can be asked, because an append-only log cannot be pruned afterwards. What clears it is proposed as one operation — move, rename to NNNN-title.md, the log's row, the missing frontmatter, the body under the required H2s — applied only on confirmation. A record holding a decision and material the expiry test rejects is split in that same proposal — the decision into the log, the rest routed as an ordinary page, a fragment belonging on no page dropped once the human says so — and only where the two come apart with no sentence rewritten. What does not clear the bar at all is routed whole or reported and left alone, in the same plan. Detection rule, the threshold gate, the split's rules, the date derivation and what is report-only instead: REFERENCE.md.
    • Report only — a how-to without a checklist, a page that fits no section, suspected duplication of an upstream source or of a file in the repo, any secret detected, missing image targets or required capture sources, suspected unused assets and missing required localized captures. Media is never auto-edited; docs-only non-use is not proof of repo-wide orphanhood (media contract).
  4. Show the plan + diff; on confirm apply only structure + frontmatter. Never rewrite prose. Only touch files inside docs/. Two exceptions, both scoped: an imported ADR, whose body is re-homed under the required H2s — a split sends part of it to a page, and a named fragment is dropped on explicit confirmation, so the author's sentences are moved or removed, never rewritten; and a locale tree, which is regenerated rather than reconciled.
  5. Regenerate every listed locale from the default tree. Where docs.locales names a locale, the sweep rewrites docs/<locale>/ — structure derived from the source, title, description and body prose translated. This is the one place a reconcile writes prose, and it is scoped to the locale trees: the default-locale tree keeps prose untouched in full. For translated pages inside a locale root structural drift is never categorized or reported — it means the sweep had not run (the rules). Translate alt text/captions and visible Mermaid labels; preserve shared media references or verified localized variants and report missing required captures. Never copy or generate media in a translation sweep. With docs.locales absent this step does not exist.

99.adr/ is exempt — links and the decision log only. An ADR id is permanent, so never renumber one, never rename it to the dot-schema, never close a gap in the sequence (REFERENCE.md). A foreign ADR is outside that exemption: it was never accepted in this log, so giving it an id is a first assignment rather than a renumbering, and shaping it on entry is not an edit to an accepted record. A translated ADR is outside it too, in the other direction: the record is the source file, its translation is a rendering of one, so a locale tree's 99.adr/ is regenerated with the rest of that tree — ids, filenames and status copied across untouched.

<skills-plan>

Presenting the plan

Everything this skill puts in front of a human — plan, preview, candidate list, findings report — is read once, in a terminal, and answered there. So every section of it renders on arrival, with no interaction needed to reveal it: prose, lists, tables, fenced code.

Never fold content behind a control. <details>/<summary> is a browser widget, and a terminal has no way to open it: the summary line prints and everything under it does not. The plan then arrives as headings with nothing beneath them, and the failure is silent on both sides — the skill believes it reported, and the reader sees no marker saying anything is missing, so a human confirms a plan whose contents never reached them. What gets folded is whatever ran long, which is to say the part the decision actually rested on. The same holds for anything else needing a click: a tab strip, an accordion, a "show more".

Length is handled by shortening, never by hiding. This is a fixed rule of the skill, not a per-run judgement, so it holds however long the list runs. Trim to what the decision needs, group the rest by something the reader already thinks in (ecosystem, kind, verdict) with a count per group, or split it across sections. What is left out is left out visibly: say how many, why, and the exact command that shows the rest.

This binds what the skill presents, not what it writes. A <details> block inside a README, an issue body, a pull request description or a docs page is rendered by a browser and is entirely legitimate there. The rule is about the message a human reads to decide — never about the content of a file.

</skills-plan>

Guardrails (inherited)

  • Docs are never the source of truth — the repo is. Code says what happens; a page exists for the why, the rejected alternatives, and the way in — the three things code cannot express. Documentation that mirrors code or a file costs tokens on every read and starts lying at the next commit, so when a page would restate one, link it and write only the delta.
  • Plan/preview first; apply only after confirmation. Respect plan-only / dry-run.
  • Keep generated content attribution-free — no agent self-naming or Generated with/🤖 lines.
  • No secrets in generated docs — scan, warn, exclude.
  • Only the requested action — nothing closed or changed unasked.
  • No cache — the docs/ tree is live state, always read fresh.
  • Translated pages are generated, never authored. Listing a locale in docs.locales binds this skill to maintain and translate it, and a sweep rewrites it from the source — so a correction made inside docs/<locale>/ does not survive. Corrections go to the source page, or to the wording guidance docs.instructions carries. A missing translation is legitimate and never a defect to fix (Locales).

Reference

  • Open it where the body's routing matrix stops deciding for you — which sections a preset scaffolds, what frontmatter and status marker a new page carries, which type a slug is allowed to be, whether a subject belongs in a folder or a section, and what a reconcile may change rather than only report: REFERENCE.md.
  • Open it before touching a repo that lists docs.locales — which tree is the default locale, what a locale root may and may not be read as, what a sweep regenerates, and where the prose untouched invariant stops holding: Locales.
  • Open it in full before writing or importing an ADR, every time. 99.adr/ is append-only, so the id, the naming, the required sections, what the body may hold and the supersession rule have to be right on entry — there is no later edit that repairs them: REFERENCE.md.
  • Open the media contract before including a capture or reconciling assets — destinations, optional capture delegation, locale sharing and report-only findings.
  • Copy one per page you are about to create, matched to that page's type: templates/. They are written for the portable default, so under the render mode apply that mode's flips as you copy — there is no second set of skeletons.

Gap report (mandatory final step)

If you used a section, page type, or preset not in REFERENCE.md, end the turn with a short note (Gap report: section "{x}" — no catalogue entry; added ad hoc.). Only report; don't edit REFERENCE.md yourself — the user folds gaps back in. A new slug is a real gap only when it names a missing type; a subject section (plugins, themes, integrations) is not — route its content into the type sections (nested if it needs grouping) and report that instead. Neither is a named non-section directory such as _partials/ or _assets/ — it is catalogued, so it never triggers a report. A locale root (de-DE/) is not a section at all, so it never belongs in this report either. If everything matched: Gap report: no gaps.

Report the gap, not the rule you had to break. A run whose pages need a form the convention forbids has hit the case the render mode exists for — say so and name docs.render, rather than reporting five separate rules as five separate gaps, or breaking them quietly. Under the mode, following its flips is the convention and is never a gap.

04 同仓库更多 Skills

TitusKirch
TitusKirch/skills

gamma

The third fixture skill — carries the worklock, plan and tldr blocks, and names the resolver without hosting the config block.

★ 3
TitusKirch
TitusKirch/skills

beta

The second fixture skill — carries the tagged blocks but no config block.

★ 3
TitusKirch
TitusKirch/skills

alpha

The first fixture skill — carries the config block and the resolver.

★ 3
TitusKirch
TitusKirch/skills

work-review

Reviews a single tracked issue's pushed implementation across GitHub (gh), GitLab (glab), Linear (MCP) or local issue files as a fresh, independent agent — reads the issue's requirements and the pushed diff, adversarially checks whether the work is correct and complete, and writes a verdict that routes the issue to done (accepted), changes-requested (feedback, back to the implement loop), needs-human (escalation), or blocked. It never implements or fixes anything — review only. It also applies a human's verdict on a needs-human issue. Tracker, labels and the round cap come from the committed config (.tituskirch-skills.json). Use when the user wants to review, check, or sign off one specific issue's AI work, mentions an issue awaiting review, or says things like "review issue 42", "check the work on issue 42", "reviewe Issue 42", or gives a verdict on an escalated issue.

★ 3
TitusKirch
TitusKirch/skills

work-review-queue

Drains a repo's queue of issues awaiting AI review across GitHub (gh), GitLab (glab), Linear (MCP) or local issue files — selects every issue in review, then reviews each with a fresh, independent agent by delegating to work-review, routing each to done, changes-requested (back to the implement loop), needs-human, or blocked. Starts by reconciling issues whose PR a human merged or closed out-of-band. Honours a per-run cap, single-flight-locked with a lock separate from the implement loop's, so review and implement drains run concurrently. Use when the user wants to review, drain, or auto-review the pushed AI work, run the review loop, says things like "review the queue", "reviewe die Issues", "drain the review queue", or starts a repeating driver.

★ 3
TitusKirch
TitusKirch/skills

work-implement

Implements a single tracked issue across GitHub (gh), GitLab (glab), Linear (MCP) or local issue files — claims it via the lifecycle label, implements on a branch (fresh from ready, or re-work from changes-requested after review feedback), runs the repo's checks, commits and PUSHES, and hands the issue to the review loop by advancing the label to review. It never reviews its own work — the separate work-review skill does that. Tracker, label lifecycle and branch strategy come from the committed config (.tituskirch-skills.json). Use when the user wants to work, implement, action or pick up one specific issue or ticket, mentions an ai-ready issue, or says things like "work issue 42", "arbeite Issue 42 ab", "implementiere Ticket X", or "address the review feedback on issue Y".

★ 3