AGENT SKILL

write-readme

Generates project READMEs in the kirchDev house style — centered hero header with emoji + bold tagline, a one-liner code-snippet hook, feature bullets with prescribed section emojis, and standardized closing sections (Versioning, License). Use when the user asks to write, draft, scaffold, or regenerate a README.md for a kirchDev / IT-Dienstleistungen Titus Kirch repository, or when starting a new repo that needs its top-level README. Do not use for editing arbitrary unrelated READMEs.

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

01 前言 Front Matter

name
write-readme
metadata
{ "summary": "Generates project READMEs in the kirchDev house style." }
description
Generates project READMEs in the kirchDev house style — centered hero header with emoji + bold tagline, a one-liner code-snippet hook, feature bullets with prescribed section emojis, and standardized closing sections (Versioning, License). Use when the user asks to write, draft, scaffold, or regenerate a README.md for a kirchDev / IT-Dienstleistungen Titus Kirch repository, or when starting a new repo that needs its top-level README. Do not use for editing arbitrary unrelated READMEs.
allowed-tools
[ "Read", "Write", "Edit", "Glob", "Grep" ]

02 资源文件 3

03 SKILL.md 正文

write-readme

Quick start

  1. Ask the user for the project name, a one-sentence tagline, the hero emoji (🛡️ packages, 🏗️ infrastructure, 📚 docs, 🧰 tooling, etc.), and a representative code snippet (the "hook").
  2. Copy templates/README.template.md and fill the placeholders.
  3. Add only the sections the project actually needs — but keep them in the canonical order and use the prescribed emoji.
  4. Show the draft and ask which optional sections to add/drop before writing the file.

Canonical structure (always in this order)

# Section Emoji When to include
1 Hero block (project) Always — <div align="center"> + # {emoji} {name} + bold tagline.
2 Badges — Only for public packages (Packagist / npm / CI / license).
3 Hook — Always — fenced code block + a single "That's it. …" sentence.
4 Installation/Stack 📦 Always (label "Installation" for packages, "Stack" for infra/apps).
5 Quick start/Setup 🚀 Always (label "Quick start" for packages, "Setup" for infra/apps).
6 Features ✨ Always — bullet list, each bullet **{emoji} Title** — body.
7 Domain sections varies As many as needed; pick emoji from the catalogue in REFERENCE.md.
8 Contributing 🤝 If the repo accepts external PRs.
9 Versioning 🛣️ Always — link to CHANGELOG.md and release-please.
10 License 📄 Always — link to LICENSE + author/org line.

[!NOTE] Installation / Quick start lead, then Features — surfacing the install/run command near the top lets a reader reach it in ~30 seconds. Merging Installation + Quick start into a single Install & run section is acceptable (and is what compact-readme produces from a scaffolded file).

Style rules

  • Hero is wrapped in <div align="center">…</div>, followed by ---.
  • Tagline is one line, bold, em-dashes for emphasis. No period unless it's a full sentence.
  • Hook uses a real, copy-pasteable snippet — the most representative thing the project does in 1–6 lines. Follow with one sentence ending in "That's it. …" pattern.
  • Feature bullets: - **{emoji} Title** — sentence. Emojis act as scannable column-1 indicators.
  • Tables: left-aligned (| :--- |).
  • Callouts: use > [!TIP], > [!IMPORTANT], > [!NOTE] — never plain blockquotes.
  • Never mirror a file the repo already ships. A README's job is the shortest path from landing to running — not a second copy of package.json's scripts, a schema's option table, an .env.example, or a workflow. Show the handful of values a newcomer needs, then link the file for the rest. A copied table is wrong at the next commit and nothing will tell you; the repo, not the README, is the source of truth.
  • License footer — copy the closing footer verbatim from templates/README.template.md, the single source for the Versioning/License blocks and the © … author line. Never retype the author/license string by hand.

Workflow

  1. Gather — name, tagline, hero emoji, hook snippet, public-or-internal, list of needed domain sections.
  2. Draft — fill templates/README.template.md; pick domain-section emojis from REFERENCE.md.
  3. Review — present the draft, confirm which optional sections to keep, then write the file.
  4. Gap report — see below.

Gap report (mandatory final step)

After writing the README, end the turn with a short report naming what REFERENCE.md prescribes but does not yet cover.

Three kinds are reportable, and nothing else. They mirror REFERENCE.md's three prescriptive tables one for one — a gap is a hole in a table that binds, so what the skill does not prescribe cannot have one. There is deliberately no catch-all line: a fourth kind arrives only when the skill grows a fourth prescriptive table, and gains its report line in that same change.

  • Hero-emoji gaps — you fell back to 📦 because no project type in the hero table matched.
  • Sections without a prescribed emoji — an H2 you had to invent an emoji for because it isn't in the section catalogue.
  • Badges without a palette color — a badge purpose that fits none of primary / neutral / success / laravel / php / node / warning.

Two things look like gaps and are not:

  • Feature-bullet emojis are free-form — never report one. REFERENCE.md's Feature-bullet emojis table says so itself: it is a suggestion list, not a catalogue, so an emoji it doesn't list is the table working as designed, with nothing to fold back in. Borrowing one from the section catalogue is fine too — the two already overlap on 🏢, 🧪, 🔍, 🧩 and 🗂️.
  • A missing badge set is not a missing palette color. The reportable case is a purpose with no token, never a project shape without a ready-made block under Standard sets. A public package that hasn't reached the registry yet takes the standard npm set unchanged — that is the decision, not a gap in it.

Format:

Gap report — improvements for write-readme:
- Hero type "{description}" — no catalogue entry; used {emoji}.
- Section "{name}" — no catalogue entry; used {emoji} as ad-hoc choice.
- Badge "{purpose}" — no palette token; used color={hex}.

If everything was covered, say so: Gap report: no gaps — every section and badge matched the catalogue.

Only report; do not edit REFERENCE.md or this skill yourself. The user decides whether to fold the gaps back in.

<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

  • Plan first; write only after confirmation — the draft and its optional sections are agreed before the file lands (Workflow step 3).
  • Keep the generated README attribution-free — no agent self-naming, no Generated with/🤖 line, no session URL. A README is the project's front door, not a record of who wrote it.
  • No secrets — the hook is real, copy-pasteable code: scan it for tokens, keys and .env values, and show a placeholder rather than a live one.
  • Only the requested action — this skill owns README.md. It never edits the files the README links to, and never commits.

Reference

  • Open it the moment a hero, a section, a feature bullet or a badge needs its house-style value. Every one of them is a catalogue lookup, never a choice a run makes for itself — a guessed emoji or an invented badge colour is exactly the drift this skill exists to prevent: REFERENCE.md.
  • Copy this first and fill it in place — the canonical section order is already in it: templates/README.template.md.

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