readme-craft

A GitHub-native, layout-first README generation and improvement skill for AI agents. Produces structured, scannable READMEs with a 3-tier information hierarchy designed for how GitHub READMEs are actually consumed.

This skill is a standalone utility. It does NOT depend on skill-forge or any other skill. Higher-level tools (like skill-forge) may optionally delegate to readme-craft for layout and badge decisions.

Execution Procedure

def readme_craft(project_path, user_request):
    # STEP 0: Dependencies
    run("scripts/setup.sh")                                    # exit non-zero → STOP

    # STEP 1: Scan
    state = scan_project(project_path)                         # see Scan section
    # state = {has_readme, has_logo, has_codebase, has_skill_md, ...}

    # STEP 2: Gather
    if state.has_codebase:
        info = derive_from_code(state)                         # see Gather section
    else:
        info = ask_user("name, one-liner, features, license")
    info += ask_targeted_questions(state, max=4)               # only when scan can't decide

    # STEP 3: README Content
    if state.has_readme and user_said("start fresh"):
        facts = extract_facts(state.readme)                    # carry forward, discard structure
        state.has_readme = False

    if state.has_readme:
        plan = evaluate(state.readme, "3-Tier Layout + Quality Checklist")  # see 3-Tier section
        if state.has_skill_md: assert_distinct_operations(plan, "Quick Start")
        confirm_plan_with_user(plan)                           # HITL — or apply if "just fix it"
        readme = apply_improvements(state.readme, plan)        # see Tone & Voice section
    else:
        template = "assets/skill-readme.md" if state.has_skill_md else "assets/universal-readme.md"
        readme = fill_template(template, info)

    # STEP 4: Logo
    if state.has_logo:
        readme = insert_picture_element(readme, state.logo)    # see Dark/Light Mode Logo section
    else:
        candidates = run(f'node scripts/generate-logo.mjs --candidates 5 --name "{info.name}"')
        present_paths_to_user(candidates)                      # HITL — user picks
        selected = wait_for_user_selection()                   # references/logo-generation.md
        copy_to(".github/logo-light.svg", generate_dark(".github/logo-dark.svg"))
        if wordmark_spells_name(selected): omit_h1()

    # STEP 5: Formatting & Badges
    readme = apply_3tier_layout(readme)                        # see The 3-Tier Layout Strategy
    readme = apply_github_formatting(readme)                   # references/github-formatting.md
    readme = select_and_apply_badges(readme, state)            # see Badge Selection + references/badges.md
    if state.has_git_remote:
        star_count = gh_api_star_count(state.remote)           # gh api repos/{owner}/{repo} --jq .stargazers_count
        if star_count >= 100:
            if ask_user(f"This repo has {star_count}⭐ — add a star history chart?"):  # HITL
                readme = insert_star_history(readme, state.remote)  # references/badges.md § Star History
    readme = apply_tone_voice(readme)                          # see Tone & Voice section

    # STEP 6: Quality Check
    # Pass 1: structural
    findings = run_checklist(readme, "dimensions 1-5")         # references/quality-checklist.md
    report_to_user(findings)
    readme = fix(readme, findings)
    assert run_checklist(readme, "dimensions 1-5").all_pass

    # Pass 2: reader lens
    reader_findings = run_checklist(readme, "dimension 6")     # different mindset — stranger perspective
    readme = fix(readme, reader_findings)

    # STEP 7: GitHub Metadata
    validate_or_create_metadata(state)                         # references/github-metadata.md
    assert metadata_file_valid(state)                          # GATE — .github/repo-meta.yml must exist with valid description + topics
    if state.has_git_remote:
        apply_metadata_to_remote(state)                        # gh repo edit --description + --add-topic

    # STEP 8: Deliver
    readme = add_footer(readme, state)                         # "Crafted with Readme Craft"
    readme = remove_sections_user_declined(readme)
    present_final(readme)

    # STEP 9: Comparison (when improving an existing README)
    if state.has_readme and state.original_readme:
        generate_comparison(state.original_readme, readme)     # references/comparison-screenshots.md

When to Use

Activate this skill when the user says any of:

"Write a README for this project"
"Generate a README"
"Create a README from scratch"
"Improve this README"
"Review my README"
"Make my README better"
"Add badges to my README"
"Fix my README layout"
Any request involving README creation, evaluation, or improvement

Scan

Scan the project to understand current state:

Check for existing README
Check for existing logo files in .github/ first, then repo root (logo-light.svg, logo-dark.svg, logo.svg, logo.png). Canonical location: .github/
Read package.json, Cargo.toml, pyproject.toml, go.mod, SKILL.md frontmatter, or equivalent for name, version, description, license, dependencies
Read existing docs (CONTRIBUTING.md, CHANGELOG.md, LICENSE) if present
Read the entry point and key source files to understand what the project does
Read CI config (.github/workflows/, .gitlab-ci.yml) to determine build/test commands
List directory structure (top 2 levels)

Record findings as project state: {has_readme, has_logo, has_codebase, has_skill_md, ...}

Gather

has_codebase → derive name, description, features, install commands from code
- Derive the one-liner from package description + source code understanding
- Derive features from exports, CLI commands, API surface, or SKILL.md capabilities
- Derive install commands from package manager config or skill registration patterns
- Derive quick-start from examples/ directory, tests, main entry point, or install command. For general projects: install command + minimal code snippet or one CLI invocation. For skill projects (has_skill_md): list distinct operations from SKILL.md workflow modes — one canonical trigger phrase + outcome per operation. Phrasing variations of the same operation go in Usage, not Quick Start
!has_codebase → ask user for: project name, one-liner, key features, license
Either way: ask up to 4 targeted questions only when the scan cannot safely decide:
- should social proof appear in the README
- should deep content move to docs/
- should a diagram be added
- should an existing voice or visual style be preserved strictly

What a README Is — and Is Not

A README is a storefront, not a documentation site. In the Diátaxis framework (tutorials, how-to guides, reference, explanation), a README does not belong to any single type. It borrows elements from several:

Explanation → Why / The Problem
How-to → Quick Start, Install, Usage
Reference → Tier 3 supporting content (inline or linked to docs/)

But a README has a mission that none of the four types cover: convince. The Features section exists to sell — to make a reader believe this project is worth their time in the fewest possible words. Features answer "what do I get?", not "how does it work internally?" or "why was it designed this way?"

The structural principle behind the 3-tier system is progressive disclosure: reveal only what each visitor needs at their current level of commitment. Tier 1 is for the uncommitted (pitch), Tier 2 is for the evaluating (proof), Tier 3 is for the committed (reference). Every placement decision — "does this belong above the fold or at the bottom?" — is a progressive disclosure decision. Scrolling is the disclosure mechanism, not collapsing.

Concept	Question it answers	Example
Features / Highlights	"What do I get?"	"Scans your codebase and auto-generates a README"
How It Works	"How does it run internally?"	"Config → Gather → Create → Validate → Publish"
Why / The Problem	"Why do I need this?"	"Your skill is trapped in one project and can't be shared"

When Features and How It Works are mixed together, the README writes out a pipeline instead of selling capabilities.

The 3-Tier Layout Strategy

This is the primary differentiator of readme-craft. Every README must organize content into three tiers based on how visitors consume information.

This strategy is optimized for GitHub README rendering. Elements like <picture> and similar GitHub-specific patterns may not render on other platforms (GitLab, npm, crates.io). Adapt as needed.

Tier 1: Above the Fold (~250px)

The first screen a visitor sees. This is the 3-second pitch. Visitors who are not interested will leave after this.

Baseline elements (in order):

Logo — centered, 80-120px height. Use existing if found, generate if not (see Step 4). Use <picture> for dark/light mode (see below).
Project name — <h1>, centered.
One-liner — a value proposition, not a technical description. Answer "why should I care?", not "what technology is this?" Example: ✓ "Stop writing validation logic by hand" vs ✗ "A TypeScript library for form validation."
Badges — up to 6, on 1-2 lines. Trust signals: license, version, build status, downloads. Fewer is fine when fewer apply.
Quick action links — inline links to the most relevant next actions (for example Quick Start, Usage, Install, Docs, Demo, Report Bug).

Additional brief elements (a platform compatibility line, a short tagline, a small demo gif) are fine as long as Tier 1 stays within ~250px and reads as a single visual block.

Rules:

The constraint is height and density, not element count. Stay within ~250px.
No walls of text above the fold.
Logo must be compact (not a full-width banner).
The one-liner must answer "why should I care?" not "what technology is this?"
No installation instructions in Tier 1.

Markdown pattern (standard):

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset=".github/logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset=".github/logo-light.svg">
    <img alt="project-name" src=".github/logo-light.svg" width="120">
  </picture>

  <h1>project-name</h1>
  <p>One-liner value proposition</p>
</div>

<div align="center">

[![License: MIT][license-shield]][license-url]
[![Version][version-shield]][version-url]
[![Build][build-shield]][build-url]

</div>

<div align="center">
  <a href="#quick-start">Quick Start</a> &middot;
  <a href="https://docs-url">Docs</a> &middot;
  <a href="https://demo-url">Demo</a>
</div>

Alternate pattern (wordmark logos):

When a wide wordmark (400-500px) serves as both logo and project name, the standard <p> inside <div> can feel cramped. Use a > blockquote after the closing </div> instead — it adds visual separation between the wordmark and the one-liner.

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset=".github/logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset=".github/logo-light.svg">
    <img alt="project-name" src=".github/logo-light.svg" width="440">
  </picture>
</div>

<!-- badges and quick links divs here -->

> One-liner value proposition

Use the standard <p> pattern by default. Switch to blockquote only when the wordmark is wide enough to make the centered <p> feel visually crowded.

Tier 2: Scan Quickly

The next 2-3 screens. A visitor who passed Tier 1 wants to evaluate whether this project is worth adopting.

Showcase Image — For tools that produce visual transformations, place a before/after or hero image immediately after Tier 1's --- separator, before the first ## heading (or as the first element of Tier 2). This is a "show don't tell" proof that's more convincing than any text description. Skip ONLY when: project has no visual transformation (CLI tools, libraries, pure APIs).

Required sections (in order):

Why / The Problem — 2-4 sentences. What pain point does this solve? A strong Problem section lets readers self-qualify: "If [your situation], you need this." If the project serves multiple user segments (e.g., "haven't started yet" vs "already deployed"), address each briefly rather than blending into one generic statement.
Features / Highlights — bullet list, benefit-oriented. Each item answers "what does the user get?", not "how does it work internally?" Write in benefit-oriented language ("scans your codebase and auto-generates a README"), not mechanism-oriented language ("uses AST parsing to extract function signatures"). If you find yourself describing pipeline stages or internal steps, move that to How It Works in Tier 3.
- Scope: 3-6 items for focused projects; scale to 7-10 for feature-rich projects. The goal is comprehensive coverage — do not cherry-pick a few capabilities and silently drop the rest. When the project has many features, group related capabilities into single items or use sub-descriptions rather than omitting.
- Ordering: Most important and most innovative capabilities first. Lead with what makes this project unique, not with table-stakes features every similar tool has.
- Comprehensiveness check: Read through all source files, reference docs, and config to inventory every user-facing capability. Then confirm every major capability appears in the Features list — either as its own item or clearly covered within another item.
When to Use — include for tools and skills. Skip ONLY when: the Usage section already covers activation context. Clarify what situation should prompt the reader to reach for this project. If there's a specific activation model ("use after X, not during Y") or a "not for" boundary, state it here. Can be combined into Usage if short.
Quick Start — the fastest path to a working example. 1-3 commands + minimal code (5-15 lines).
Install — primary installation method inline. Alternative methods: short → inline below primary; long → docs/install-alternatives.md with teaser.
Usage — basic example + 1-2 common use cases. Advanced examples: short → inline; long → docs/ with teaser.

Rules:

Each section must fit on one screen or less.
Use code blocks aggressively — they scan faster than prose.
Bullet lists over paragraphs.
If a section exceeds one screen, move detail into a linked doc (docs/).

For AI agent skills, "Usage" (trigger phrases) may come before "Install" to prioritize understanding over commitment. The skill template reflects this ordering.

Tier 3: Supporting Content

Sections below Tier 2 that serve committed users. Position at the bottom of README provides natural progressive disclosure — scrolling is the disclosure mechanism, not collapsing.

The Checkout Test — the operational criterion for every section:

If this section disappeared from the README, would a potential user be less likely to git clone or npm install the project?

Yes → keeps the section inline in README

No → section moves to docs/ with a teaser link

Three content types pass the Checkout Test:

Feasibility gates — "Can I use this?" (Prerequisites, primary Install, License)
Value proposition — "Should I use this?" (Why, Features, Quick Start, When to Use)
Trust signals — "Can I trust this?" (Badges, social proof)

Everything else is post-decision content: "how to use it better" or "how it works internally." Removing it would not change whether someone tries the project.

Section-by-section reference:

Section	Passes Checkout Test?	Category	Placement
Why / Problem	Yes	Value proposition	Tier 2 inline
Features	Yes	Value proposition	Tier 2 inline
Quick Start	Yes	Value proposition	Tier 2 inline
When to Use / Not-for	Yes	Value proposition	Tier 2 inline
Install (primary)	Yes	Feasibility gate	Tier 2 inline
Prerequisites	Yes	Feasibility gate	inline
License	Yes	Feasibility gate	inline
Install (alternatives)	No	Post-decision (exploring options)	teaser + `docs/`
How It Works	No	Post-decision (curiosity)	teaser + `docs/`
Configuration (full)	No	Post-decision ("configurable" helps; full table doesn't)	teaser + `docs/`
API Reference	No	Post-decision	teaser + `docs/`
Project Structure	No	Post-decision (contributor info)	teaser + `docs/`
Development	No	Post-decision (contributor info)	teaser + `docs/`
Contributing	No	Post-decision (contributor info)	inline or CONTRIBUTING.md
Changelog / Roadmap	No	Post-decision (existing users)	teaser + `docs/` or link
Acknowledgments	No	Post-decision (courtesy, usually very short)	inline

No <details>. Zero. If content is worth including, show it inline. If it's too long for README, move it to docs/ as a complete, self-contained document. No folding, no collapsing.

Teaser + link pattern — substantive summary, not "learn more":

## How It Works

skill-forge validates structure, security, and claims in a single pass
by reading every file in your skill repo.

→ [Architecture deep dive](docs/how-it-works.md)

HITL: readme-craft proposes moves ("suggest moving How It Works to docs/how-it-works.md"). The user confirms before execution. Never auto-move content out of README.

Rules:

Non-decision sections → docs/ with teaser. Exception: very short sections (< 5 lines, e.g., Acknowledgments, License) stay inline.
Teaser = 1-3 substantive sentences + → [Title](docs/X.md) link. The teaser IS the summary for anyone who doesn't click.
Contributing: inline or CONTRIBUTING.md — not docs/.
Add a back-to-top link for READMEs exceeding 300 lines.
Use reference-style link definitions at the bottom of the file for badge URLs.

Badge Selection

Choose badges based on the project's ecosystem and maturity. Up to 6 badges; fewer is fine when fewer apply.

Priority order (pick from top, stop at 6):

Priority	Badge	When to Include
1	License	Always
2	Version / Release	Always (npm, PyPI, crates.io, or GitHub release)
3	Build / CI status	If CI is configured
4	Downloads	If published to a package registry
5	Coverage	If coverage reporting is set up
6	Platform / ecosystem	If relevant (e.g., Agent Skills compatible, Node.js version)

Badge sources:

shields.io — the standard for most badges
GitHub Actions badge URLs — for CI status
Custom badges — only if shields.io does not cover the case

Format: Use reference-style links at the bottom of the README to keep the source markdown clean.

[![License: MIT][license-shield]][license-url]

<!-- at bottom of file -->
[license-shield]: https://img.shields.io/github/license/org/repo.svg
[license-url]: https://github.com/org/repo/blob/main/LICENSE

For copy-paste badge patterns organized by ecosystem, see references/badges.md.

Dark/Light Mode Logo

GitHub supports theme-aware images via the <picture> element. Always include this pattern when the project has a logo.

The pattern:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset=".github/logo-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset=".github/logo-light.svg">
  <img alt="project-name" src=".github/logo-light.svg" width="120">
</picture>

Rules:

Prefer SVG for logos (scales cleanly, small file size).
The <img> fallback uses the light variant (GitHub default theme).
Store logos in .github/ (per skill-forge asset placement convention: logo and screenshots are repo infrastructure, not skill runtime content).
If the project only has one logo, use the same path for both srcset values and the src — still include the <picture> wrapper so a dark variant can be added later without restructuring.
Width 80-120px for inline logos (icon/symbol marks). Wordmark logos (text-rendered SVGs like figlet/cfonts output) may use 400-500px width since they serve as both logo and project name. Never use full-width banners in Tier 1.
If no logo exists yet, generate one (see Step 4). Every delivered README includes a logo.

Fallback wordmarks:

If the project has no logo, generate logo candidates using --candidates N mode instead of silently picking one preset.
Present absolute file paths to the user for preview. Let them choose.
Use --random mode only when the user explicitly says "surprise me" or "just pick one".
For a visual gallery of all available presets and palettes, see docs/logo-gallery.md.
Prefer visually single-line wordmarks for README headers. If a preset reads like stacked block art or creates a double-title feel, switch to an inline treatment.
If the generated wordmark already renders the project name clearly, omit the duplicated <h1> by default unless the user explicitly wants both.
For preset selection rules and examples, see references/logo-generation.md and references/logo-examples.md.

GitHub-Native Formatting Decisions

Use GitHub-specific formatting when it improves comprehension, not because it exists.

For syntax patterns and deeper rules, see references/github-formatting.md.

Default patterns:

Relative links for docs/, sibling markdown files, and split reference material
Teaser + docs/ link for long non-decision content
Tables for structured data
Minimal HTML where Markdown is not enough (e.g., <picture> for dark/light logos)

Optional patterns:

Mermaid diagrams for architecture, flow, sequence, timeline, or dependency relationships
Task lists for roadmap or status
Footnotes for citations and side notes
Math expressions for technical projects that genuinely need formulas
Social proof elements such as contributor widgets or star counts

Rules:

Do not move decision-making content (Tier 2 sections) to docs/ — it must stay inline.
Use relative links when splitting a long README into docs/ or separate markdown files.
Add diagrams only when they explain faster than prose.
Add social proof only when the repo is public, the numbers are real, and the user wants it.
Prefer clarity over visual novelty.

docs/ Content Standard

docs/ exists to serve README. When a non-decision section is moved out of README, the full content goes to a docs/ file. readme-craft creates these files as part of README improvement — it does not manage or reorganize existing project documentation.

Boundary: docs/ is a human-facing layer. It must NOT be referenced by SKILL.md, references/, or any agent-facing instruction file. For skill repos: agent-relevant content belongs in SKILL.md + references/; docs/ is for humans who want depth beyond what README shows.

Naming: kebab-case by topic (how-it-works.md, configuration.md). Keep docs/ flat. Every file should be self-contained — readable without the README.

Scale: Most small projects need 0 docs. Don't create docs/ preemptively. Only create files when moving content out of README. If a project has no non-decision sections longer than ~15 lines, it doesn't need docs/.

Tone & Voice

When writing README content, follow these guidelines:

Address the reader as "you" — not "the user" or "one."
Refer to the software in third person — "readme-craft generates..." not "we generate..."
Value proposition over technical description — lead with what the reader gains, not what the software is.
Professional but direct — no exclamation marks, no emoji, no hype words ("revolutionary", "blazing fast").
Concise — if a sentence doesn't add information, cut it.

When improving an existing README, these guidelines are recommendations, not overrides. Preserve the author's existing voice unless they explicitly ask for a tone change.

Example Provenance

When including an Example section in a README:

If the example comes from a real run, keep paths, commands, and outputs specific.
If the example is a sample flow, say so explicitly.
Never present unverified repo URLs, release pages, docs links, or install commands as if they already exist.

Quality Checklist

Run the checklist in references/quality-checklist.md before delivering any README. Report failures to the user.

The checklist covers 6 dimensions: Structure (7), Content (13), Formatting (10), User Perspective (5), Completeness (6), Reader Lens (4) — 45 checks total. Dimensions 1-5 are structural; dimension 6 requires a mindset shift to first-time reader perspective.

References

This skill uses the following template and analysis files:

File	Purpose
`assets/universal-readme.md`	Base template for any OSS project. Contains all three tiers with placeholder markup.
`assets/skill-readme.md`	Extended template for AI agent skills. Adds Agent Skills badge, trigger phrases, `npx skills add` install, and "What's Inside" section.
`references/badges.md`	Copy-paste badge patterns for shields.io, organized by category (license, version, CI, downloads, coverage, platform, Agent Skills).
`references/github-formatting.md`	GitHub-native formatting patterns, overflow strategy, and rules for diagrams, footnotes, math, task lists, and social proof.
`references/logo-generation.md`	README fallback logo guidance: positioning, preset selection, runtime requirements, and when to use the local wordmark generator.
`references/logo-examples.md`	Short example mappings from project feel to recommended logo presets.
`references/quality-checklist.md`	45-point quality checklist across 6 dimensions: structure, content, formatting, user perspective, completeness, reader lens.
`references/gradient-palettes.md`	2026-curated gradient palette reference with 45 named gradients for logo and badge color selection.
`references/comparison-screenshots.md`	Before/after comparison PNG generation via Playwright for README case studies.
`references/github-metadata.md`	GitHub repository metadata: About/description rules (≤350 chars), topic 3-tier selection, `.github/repo-meta.yml` format, `gh repo edit` workflow.
`docs/logo-gallery.md`	Visual gallery of all logo presets with rendered SVG previews, palette table, and selection guidance.

When generating a README, always start from the appropriate asset template file. Read it, fill its placeholders, then adjust sections based on the project's needs.