agentsclimarketplace

Write readme

Skill TitusKirch/skills/skills/docs/write-readme

Agent skills by Titus Kirch — installable via skills.sh in Claude Code, Codex, Cursor, OpenCode and friends.

Install
npx -y skills add TitusKirch/skills --skill write-readme

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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.

SKILL.md

7.9 KB, as published. Nobody here has run it

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)

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

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

Format:

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

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

Gives 0 of the 12 instructions most readme changelog skills give

Counted across 471 of the 478 authors here whose files we hold, read 2026-08-06

  • follow the Keep a Changelog formatin 31 of 471, across 26 files
  • omit empty sectionsin 21 of 471
  • Run from the git repository rootin 20 of 471, across 7 files
  • save output directly to CHANGELOG.mdin 20 of 471, across 7 files
  • Group commits into logical categoriesin 19 of 471, across 6 files
  • Review the generated changelog before publishingin 19 of 471, across 6 files
  • Apply changelog guidelines and brand voicein 18 of 471, across 5 files
  • Exclude internal commits like refactoring and testsin 18 of 471, across 5 files
  • Specify date ranges for focused changelogsin 17 of 471, across 4 files
  • Convert technical commits into customer languagein 17 of 471, across 4 files
  • group commits by conventional commit typein 14 of 471
  • insert new entry below unreleased sectionin 14 of 471

Said here and by no other author read

  • ask user for project name tagline hero emoji and hook
  • copy readme template and fill placeholders
  • keep sections in canonical order with prescribed emoji
  • wrap hero block in center aligned div
  • use real copy-pasteable code snippet for hook
  • format feature bullets as bold emoji title and body

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.