| name | readme-craftsman |
| description | Create, update, or review a repository README when the user explicitly asks for README work. Use it to draft a new README, refresh an existing README after project changes, or audit a README against the current repository. Do not use it for general documentation, API docs, architecture docs, or documentation tasks that do not specifically target a README file. |
README Craftsman
Create, update, or review README files by analyzing the actual repository and tailoring output to the project type and audience. Works for any GitHub repository — software projects, documentation sites, datasets, research repos, tutorials, community collections, and more. The goal is to produce READMEs that are accurate, scannable, and genuinely useful — not generic filler.
Workflow
Detect Mode → Analyze Project → Classify Type → [Interview if Creating] → Generate/Update/Review → Quality Check → Deliver
Invocation posture: manual-first
When Not To Use
Do not use this skill for:
- General documentation work that does not specifically target a
README.md
- API references, architecture docs, runbooks, docs-site pages, or standalone user guides
- Generic writing requests where the user has not asked for README creation, README updates, or README review
If the repository needs broader documentation work, use a documentation or writing workflow that matches that artifact instead of stretching this skill beyond README scope.
Step 1: Detect Task Mode
| Mode | When | Approach |
|---|
| Create | No README exists, or user asks to "create / write / generate a README" | Full generation from codebase analysis |
| Update | README exists and code has changed, or user says "update / refresh / sync the README" | Targeted section updates, preserving existing voice |
| Review | User says "review / check / audit the README" | Compare README against actual project state, report findings |
Edge case — placeholder README: If a README exists but contains only a title, one line of description, or obvious auto-generated stub content, treat it as Create mode (full generation) rather than Update mode. The existing content is not worth preserving.
If the mode is still ambiguous after applying the above, ask.
Generic requests like "write docs", "document the API", "improve the docs site", or "write architecture documentation" are out of scope unless the user specifically wants README work.
Step 2: Deep Project Analysis
Before writing a single line, understand the project. This is what separates a useful README from a template dump.
Metadata Discovery
Read whichever of these exist to extract name, version, description, dependencies, scripts, and entry points:
Software projects:
- JS/TS:
package.json, tsconfig.json
- Python:
pyproject.toml, setup.py, setup.cfg, requirements.txt
- Rust:
Cargo.toml
- Go:
go.mod
- Ruby:
Gemfile, *.gemspec
- Java/Kotlin:
pom.xml, build.gradle, build.gradle.kts
- PHP:
composer.json
- .NET:
*.csproj, *.sln
Non-code projects:
- Doc sites:
mkdocs.yml, docusaurus.config.js, .vitepress/, book.toml, _config.yml (Jekyll)
- Datasets:
datapackage.json, dataset_info.json, large .csv/.parquet/.jsonl files, data/ dir
- Academic:
paper.tex, paper.pdf, notebooks/, experiments/, figures/
- Tutorials: Numbered directories (
01-intro/, 02-basics/), exercises/, solutions/
- Blogs:
_posts/, content/posts/, hugo.toml, gatsby-config.js, astro.config.mjs
- Community:
awesome-*.md, curated link lists, .github/ org repo patterns
Universal checks:
LICENSE / LICENSE.md — detect license type.github/workflows/ — CI/CD pipelines, release workflowsDockerfile, docker-compose.yml — containerization setupCONTRIBUTING.md, CODE_OF_CONDUCT.md — community docs already present.env.example, .env.template — required environment variablesMakefile, justfile, Taskfile.yml — available commands
Repository Structure
- Map the directory tree (2-3 levels) to understand project layout
- Identify if this is a code project or a content/data/community project
- For code: primary language(s), framework(s), entry points, test setup
- For content: content format (Markdown, LaTeX, notebooks), organization pattern, build/deploy pipeline
- For data: file formats, size, schema info, provenance
- Check for monorepo indicators (workspaces, lerna, turborepo, nx)
Existing Documentation
- Read existing README if present (for Update/Review)
- Check for
docs/ directory, wiki links, or API doc generation
- Scan key files for inline comments or metadata
- Review git log briefly for project maturity and activity level
Step 3: Classify Project Type
Classification drives section selection, tone, and which template reference to read. Determine from repository signals:
Software Projects → read references/templates.md
| Type | Typical Signals | Primary Audience | Tone |
|---|
| OSS Library | Published to package registry, exports API, has tests | Developers evaluating + integrating | Technical, concise, API-focused |
| Web Service / API | Server code, routes, database, deployment config | Developers deploying + operating | Operational, setup-heavy |
| CLI Tool | Binary/command entry, arg parsing, help text | End users installing + running | User-friendly, command-focused |
| Personal / Portfolio | Solo author, experimental, learning focus | Future self, portfolio viewers | Casual, highlights learnings |
| Internal / Team | Private repo, team references, internal URLs | Teammates, new hires onboarding | Practical, runbook-style |
| Monorepo | Workspace config, multiple packages/services | Contributors scoping to specific packages | Navigation-focused, per-package pointers |
| Config / Dotfiles | Config files, shell scripts, symlinks | Future self (confused) | Pragmatic, explains "why not just what" |
Content & Education Projects → read references/templates-content.md
| Type | Typical Signals | Primary Audience | Tone |
|---|
| Documentation / Knowledge Base | mkdocs.yml, docusaurus config, docs/ heavy, specification files | Readers seeking info, contributors adding docs | Clear, navigational, explains structure |
| Tutorial / Course | Numbered chapters/modules, exercises/, solutions/, progressive difficulty | Learners at a specific skill level | Encouraging, structured, prerequisite-aware |
| Blog / Content | _posts/, content/ dir, static site config (Hugo/Jekyll/Gatsby/Astro) | Readers, potential contributors | Inviting, explains how to read and how to write |
Data & Research Projects → read references/templates-research.md
| Type | Typical Signals | Primary Audience | Tone |
|---|
| Dataset | Large CSV/parquet/jsonl files, data/ dir, datapackage.json, data dictionaries | Data scientists, researchers using the data | Precise, schema-focused, provenance-aware |
| Academic Research | paper.tex/pdf, notebooks/, experiments/, figures/, requirements with ML libs | Researchers reproducing or building on the work | Rigorous, reproducibility-focused, citation-ready |
Community Projects → read references/templates-community.md
| Type | Typical Signals | Primary Audience | Tone |
|---|
| Awesome List | awesome-*.md filename, curated link lists organized by category, Awesome badge | Community members browsing, contributors adding | Welcoming, scannable, contribution-focused |
| Organization Profile | .github repo at org level, profile/README.md, org-wide community health files | GitHub visitors, potential contributors | Mission-driven, project showcase |
| Resource Hub | Topic collection without strict awesome-list format, roadmaps, cheat sheets, study guides | Learners or practitioners in the topic area | Educational, navigation-first |
references/templates-community.md contains a template for each of these sub-types — read the matching one.
If uncertain, confirm with the user.
Step 4: Interview (Create Mode)
When creating from scratch, ask only what the codebase can't tell you. Keep this brief — skip questions already answered by the analysis.
All project types:
- What's the one-line pitch? — If the repo has no description, ask. This becomes the opening line.
- Anything to exclude? — Sections that don't apply or content to keep private
Software projects — also ask if not inferable:
3. Who is the primary audience? — Confirms project type (e.g., external developers vs. internal team)
4. Key differentiators? — What sets this apart from alternatives
Datasets — also ask if not inferable:
3. How was the data collected or generated? — Methodology for the Data Collection section
4. Known limitations or biases? — Goes in the Known Limitations section
5. Preferred citation format? — DOI, BibTeX, or plain text
Academic research — also ask if not inferable:
3. Which paper does this accompany? — Title, venue, and link (arXiv, DOI, or publisher)
4. What are the hardware/environment requirements to reproduce the results?
Tutorials / courses — also ask if not inferable:
3. What's the target skill level? — Beginner / intermediate / advanced, and prerequisite knowledge
4. Is this self-paced or used in a structured course? — Affects tone and pacing guidance
Documentation / knowledge bases — also ask if not inferable:
3. Who is the primary reader? — New users, contributors, operators, or a mixed audience
4. Where should a first-time reader start? — Entry point, reading order, or top task
Blogs / content collections — also ask if not inferable:
3. Who is the intended audience? — Practitioners, learners, customers, or a general audience
4. Is this an actively published collection or a curated archive? — Affects navigation and freshness cues
Community / resource hubs — also ask if not inferable:
3. What belongs in the collection and what is out of scope? — Clarifies curation boundaries
4. How should contributions be reviewed or maintained? — Sets expectations for contribution guidance and freshness notes
After drafting, ask: "Anything I missed or got wrong?"
Step 5: Generate, Update, or Review
Create Mode
Select sections using references/section-guide.md. It contains the project-type section matrix, the section writing guide, and a compact GitHub Markdown feature reference. For full templates, read the reference file indicated by the project type in Step 3:
- Software projects →
references/templates.md
- Content & education →
references/templates-content.md
- Data & research →
references/templates-research.md
- Community →
references/templates-community.md
Writing Principles:
- Lead with the problem. The first thing a reader should grasp is what pain this addresses — not how clever the implementation is.
- Cognitive funneling. Broad → specific. Name → one-liner → visual → usage → install → API → contributing. A reader should get value even if they stop early.
- Show, don't claim. Replace "blazing fast" with a benchmark. Replace "easy to use" with a 3-line example. Let the reader judge.
- Copy-pasteable commands. Every command works when pasted. Full commands, not just flags. Pin versions where it matters.
- Earn every sentence. If a section adds no value for the target audience, omit it. A 50-line README for a small utility is better than a 500-line one padded with boilerplate.
- Trust signals near installation. Badges (CI status, version, license) go above the fold so readers see them before investing effort.
Update Mode
- Identify what changed — Diff the codebase against what the README describes
- Map changes to sections:
| Change | README Section(s) to Update |
|---|
| New feature / export | Features, Usage, API Reference |
| New dependency / runtime | Prerequisites, Installation |
| New env variable | Configuration / Environment Variables |
| New CLI command / flag | Usage |
| Architecture change | Architecture, directory tree, diagrams |
| New deployment target | Deployment |
| Version bump | Badges, title, installation commands |
| New chapter / module (tutorials) | Table of Contents, Curriculum |
| New data file / column (datasets) | Data Description, Schema, File Inventory |
| New curated entry (awesome lists) | Relevant category section |
| New blog post category | Content overview, navigation |
| Paper revision (academic) | Abstract, Results, Citation |
- Preserve existing voice — Match the current style, tone, and formatting. Don't rewrite accurate sections.
- Show changes before applying — Present proposed changes in one of these forms, then wait for confirmation:
- For small edits (1-3 sections): show the before/after for each changed section inline
- For larger changes: list what will be added, removed, or modified with a brief rationale for each
- Validate cross-references — Links, file paths, and version numbers must remain valid.
Review Mode
- Reality-check every claim — Do install commands work? Are listed features current? Are file paths valid?
- Flag staleness — Version numbers, screenshots, API examples, dependency lists that may be outdated
- Assess completeness — Compare against the section matrix for this project type in
references/section-guide.md
- Check quality — Run the Anti-Pattern checklist
- Deliver a report with findings categorized as:
- Critical — Incorrect information (broken install, wrong API)
- Should Fix — Missing important sections, stale content
- Nice to Have — Visual polish, missing badges, format improvements
Section Guide
Use references/section-guide.md whenever you need:
- the full section matrix by project type
- concrete section-order guidance
- copy-pasteable Markdown examples for installation, Mermaid, FAQ, and similar sections
- a quick reminder of GitHub-native Markdown features that improve scannability
Quality Checklist
Run this before delivering:
Must Pass
Should Pass
Nice to Have
Anti-Patterns
| Pattern | Problem | Fix |
|---|
| Wall of text, no structure | Readers scan, not read | Headers, tables, lists, code blocks |
| "Easy to use" / "blazing fast" | Unsubstantiated claims erode trust | Show a code example or benchmark |
| 10+ badges | Obscures the description | 3-5 meaningful badges |
| No install steps | "Just run it" isn't obvious | Full commands with prerequisites |
| Stale screenshots | Creates confusion | Use generated diagrams, or date screenshots |
| 500-line API dump | Nobody reads it | Link to API docs, show top examples |
| Duplicating CONTRIBUTING.md | Diverges over time | Link to the file, don't copy |
| "Active development" + no commits in 2 years | Dishonest | Reflect actual project status |
| README longer than the code | Overkill for small projects | Scale README to project size |
Exclusion Rules
Do not duplicate the full contents of dedicated repo files inside the README. Brief, navigational sections that point readers to these files are acceptable when they help orientation, but do not copy the full policy text.
These files usually deserve a short link or summary, not a pasted duplicate:
- LICENSE → link to
LICENSE file
- CONTRIBUTING → link to
CONTRIBUTING.md
- CHANGELOG → link to
CHANGELOG.md or GitHub Releases
- CODE_OF_CONDUCT → link to
CODE_OF_CONDUCT.md
- SECURITY → link to
SECURITY.md
If these files exist, link to them or add a very short navigational summary. If they don't exist, don't invent them inside the README.
Examples
Example 1: Creating a README for a new npm library
User: "Write a README for this project"
→ Detect: no README.md exists → Create mode
→ Analyze: package.json (name: "retry-fetch", exports, deps), src/ has 3 modules, jest tests, MIT license
→ Classify: OSS Library (npm package, exports API)
→ Interview: "This looks like an npm library for HTTP retries. Any key differentiators?"
→ Generate: Title + 3 badges, one-liner, install, quick usage example, API reference, testing, contributing link, license
→ Quality check: all commands verified, no placeholders
→ Deliver with summary of design choices
Example 2: Updating after adding features
User: "I added WebSocket support and a new --verbose flag, update the README"
→ Detect: README exists + user specifies changes → Update mode
→ Map: WebSocket → Features + Usage + API; --verbose → Usage/CLI section
→ Preserve: existing tone, badge style, section ordering
→ Show diff before applying
Example 3: Auditing an existing README
User: "Is this README still accurate?"
→ Detect: review request → Review mode
→ Compare: README claims vs codebase reality
→ Find: badge shows v1.2 but package.json is v2.0; install command missing new peer dep; screenshot shows old UI
→ Report: 3 Critical, 2 Should Fix, 1 Nice to Have — with specific fixes for each
Example 4: Creating a README for an awesome list
User: "Write a README for this repo, it's a curated list of AI tools"
→ Detect: no README → Create mode
→ Analyze: awesome-ai-tools.md with 200+ links, organized by category, CONTRIBUTING.md with submission rules
→ Classify: Community / Organization (awesome list pattern)
→ Generate: Title + badges (awesome badge, PR welcome), description, table of contents, content overview by category, contributing guidelines, license
→ Quality check: all links verified, categories complete
Example 5: Creating a README for a dataset
User: "Create a README for this dataset repo"
→ Detect: no README → Create mode
→ Analyze: data/ with 3 parquet files, datapackage.json, LICENSE (CC-BY-4.0), notebooks/ with analysis examples
→ Classify: Dataset (data files, schema metadata, CC license)
→ Generate: Title + badges, description, data overview table (files, rows, columns, size), schema, how to load (Python/R examples), citation, license, provenance
Caveats
- Scale README to project complexity. A 3-file utility needs 30-50 lines, not 500. A large framework needs depth.
- Don't overuse emojis unless the project's existing style uses them.
- Screenshots require files to exist. If images don't exist yet, recommend what to capture and where to store them, rather than referencing phantom files.
- This skill writes READMEs, not full docs. For standalone API docs, architecture docs, or user guides, suggest separate documentation tools.
- Non-code repos need different instincts. For datasets, focus on schema and provenance over install steps. For tutorials, focus on prerequisites and learning path. For community repos, focus on contribution flow and navigation. Let the project type guide which sections matter.
- When in doubt, ask. Project type, audience, and tone are judgment calls. Confirm with the user rather than guessing.
