create-readme · v1.1.0 · 2026-09-05 · sha256 7399935d07848762

create-readme v1.1.0A

Immutable. This exact content is served forever at /api/v1/blob/7399935d07848762.

---
name: create-readme
license: MIT
description: Use when generating or updating professional README.md and CHANGELOG.md files for a project. Covers repository analysis, stack detection, badge generation, structure diagrams, and alignment with Keep a Changelog and SemVer standards. Do NOT use for API-reference docs (use dedicated doc tooling), licenses/governance documents, or internal code documentation (use docstrings/JSDoc).
metadata:
  version: "1.1.0"
  visibility: public
  author: afonsoft
  url: https://github.com/afonsoft/skills
---

# Create README and CHANGELOG

## Overview

Transforms a raw repository into a well-documented project by generating professional `README.md` and `CHANGELOG.md` files based on empirical evidence from the codebase, git history, and configuration files. Every claim in the generated documentation must be traceable to a file, commit, or config in the repository.

## When to Use

- When a project lacks a README or CHANGELOG.
- When existing documentation is outdated, incomplete, or inconsistent.
- Before shipping a new version to ensure the changelog is up to date.
- When restructuring a project and the existing documentation no longer reflects the architecture.
- When onboarding new contributors and the README doesn't answer "what is this, how do I run it, how do I test it?"

## When NOT to Use

- **API reference docs** — use OpenAPI/Swagger, TypeDoc, Sphinx, or docfx instead.
- **License files** — copy the appropriate license text directly (MIT, Apache-2.0, etc.).
- **Internal code documentation** — use docstrings, JSDoc, TSDoc, or XML doc comments.
- **Architecture diagrams** — use the `drawio-architecture` skill for visual system design.
- **Agent harness setup** — use `create-agent-harness` for CLAUDE.md/AGENTS.md and skill scaffolding.

## Process

### Phase 1: Discovery (Evidence Gathering)

Before writing a single line, analyze the target repository:

**Structure analysis:**
- Root directory tree and top-level files (`ls -la`, `find . -maxdepth 2 -type f`)
- Identify entry points (`main.ts`, `Program.cs`, `__main__.py`, `index.js`)
- Detect monorepo vs. single-package layout

**Stack detection:**
- **Node.js**: `package.json` (name, version, scripts, dependencies, engines)
- **.NET**: `*.csproj`, `*.sln` (TargetFramework, PackageReferences, SDK version)
- **Python**: `pyproject.toml`, `setup.py`, `requirements.txt`, `Pipfile`
- **Java**: `pom.xml`, `build.gradle` (groupId, artifactId, Java version)
- **Go**: `go.mod` (module path, Go version, requires)
- **Rust**: `Cargo.toml` (name, edition, dependencies)
- **Docker**: `Dockerfile`, `docker-compose.yml` (base image, exposed ports, services)
- **CI/CD**: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `azure-pipelines.yml`

**History analysis:**
- `git log --oneline -n 50` — recent features and fixes
- `git tag --sort=-creatordate | head -10` — recent releases
- `git log --since="last tag" --oneline` — unreleased changes

**Existing docs:**
- Current `README.md` and `CHANGELOG.md` (if any) — reuse valid content
- `docs/` directory — reference but don't duplicate
- `LICENSE` file — extract license type

**Requirement**: Output a "Discovery Summary" containing:
```markdown
## Discovery Summary
- **Stack**: [languages, frameworks, versions]
- **Architecture**: [monorepo/single, layers, patterns]
- **CI/CD**: [platforms, pipelines, badges available]
- **Entry points**: [main files]
- **Test command**: [how to run tests]
- **Recent releases**: [last 3 tags]
- **Unreleased changes**: [commits since last tag]
- **Gaps**: [what's missing from current docs]
```

Wait for confirmation before proceeding to Phase 2.

### Phase 2: README.md Authoring

Generate the README following this strict order. Skip sections where no evidence exists — do not invent content.

#### 2.1 Title & Badges
- Project name from `package.json`/`*.csproj`/`pyproject.toml` or directory name
- Badges: CI status (from workflow file), license (from LICENSE file), version (from package manifest), language coverage (if configured)
- Badge format: `[![Name](url)](link)`

#### 2.2 Project Description
- **One-sentence summary** (what it does, for whom)
- **Rich paragraph** (functional and strategic overview)
- Evidence: derive from code comments, existing docs, commit messages — never guess

#### 2.3 Repository Structure
```text
project-root/
├── src/              # Source code
├── tests/            # Test suite
├── docs/             # Documentation
├── .github/workflows # CI/CD pipelines
└── package.json      # Node.js manifest
```
- One-line description per top-level directory
- Only include directories that actually exist

#### 2.4 Tech Stack
| Layer | Technology | Version |
|-------|-----------|---------|
| Language | TypeScript | 5.x |
| Framework | Next.js | 15.x |
| Database | PostgreSQL | 16 |
| CI | GitHub Actions | — |

- Versions from package manifests, not guesses
- Include runtime requirements (Node version, Python version, .NET version)

#### 2.5 Architecture
- Layers and patterns (Clean Architecture, DDD, MVC, microservices)
- Mermaid diagram if the system has 3+ interacting components
- Evidence: derive from directory structure and dependency graph

#### 2.6 System Flow
- Mermaid sequence/flow diagram for the main use case
- Or textual step-by-step description for simple systems
- Only include if the flow is non-obvious from the code

#### 2.7 Getting Started
```bash
# Prerequisites
node >= 20.x

# Install
npm install

# Configure
cp .env.example .env  # then edit values

# Run
npm run dev
```
- Prerequisites with specific versions
- Environment variables (names only, never values — link to `.env.example`)
- Install and run commands from `scripts` in package manifest or Makefile

#### 2.8 Tests & Coverage
```bash
npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
```
- Commands from package manifest scripts or Makefile
- Coverage threshold if configured (`.nycrc`, `jest.config`, `coverlet`)
- Badge if coverage reporting is set up

#### 2.9 Business & Technical Views
- **Business**: strategic goals, target users, problem solved
- **Technical**: key design decisions, trade-offs, constraints
- Only include if evidence exists in docs, comments, or commit messages

#### 2.10 License & Status
- License type from `LICENSE` file
- Project status: active, maintained, experimental, deprecated (from recent commit activity)
- Link to full license text

#### 2.11 Links
- Internal references (`docs/`, `CHANGELOG.md`, contributing guide)
- External references (homepage, demo, API docs) if they exist

**Rules:**
- Reuse existing content where applicable — don't rewrite what's already correct
- Only include sections where concrete evidence exists
- Default to English (en-us); only use another language if the repository's existing documentation is consistently in that language
- Never hardcode secrets, API keys, or environment variable values

### Phase 3: CHANGELOG.md Authoring

Follow the [Keep a Changelog](https://keepachangelog.com/) and [SemVer](https://semver.org/) standards:

#### 3.1 Structure
```markdown
# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added
- New feature X (commit abc123)

### Fixed
- Bug Y in module Z (commit def456)

## [1.2.0] - 2025-01-15

### Added
- Feature A

### Changed
- Updated dependency B to v2.0

[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/repo/releases/tag/v1.2.0
```

#### 3.2 Categories
- `Added` — new features
- `Changed` — changes in existing functionality
- `Deprecated` — soon-to-be removed features
- `Removed` — removed features
- `Fixed` — bug fixes
- `Security` — vulnerability fixes

#### 3.3 Source
- Populate `[Unreleased]` by analyzing `git log --since="last tag" --oneline`
- Map commit prefixes (`feat:`, `fix:`, `breaking:`) to changelog categories
- For past versions, use `git log v1.1.0..v1.2.0 --oneline` between tags
- If no tags exist, create `[Unreleased]` from the last 50 commits

#### 3.4 Linking
- Link version numbers to GitHub compare URLs: `https://github.com/{owner}/{repo}/compare/v{prev}...v{curr}`
- Link tags to release pages: `https://github.com/{owner}/{repo}/releases/tag/v{version}`

### Phase 4: Delivery & Verification

#### 4.1 Branching
Create a dedicated branch:
```bash
git checkout -b feature/{YYYYMMDD}-readme-changelog
```

#### 4.2 Linting
- Run a Markdown linter if available (`markdownlint`, `remark`, `vale`)
- Check for broken internal links
- Verify Mermaid diagram syntax (if included)

#### 4.3 Commit
Use Conventional Commits:
```bash
git commit -m "docs(readme): update README and CHANGELOG

- Add tech stack table from package.json analysis
- Add getting started section with verified commands
- Populate CHANGELOG [Unreleased] from git log since v1.2.0

Generated with [Devin](https://devin.ai)"
```

#### 4.4 Reporting
Provide a summary of changes:
```markdown
## Summary
- **README.md**: [created/updated] — added sections X, Y, Z
- **CHANGELOG.md**: [created/updated] — added [Unreleased] with N entries
- **Evidence**: all claims traced to files/commits in Discovery Summary
```
Do not open the PR automatically — let the human reviewer decide.

## Common Mistakes

| Mistake | Impact | Fix |
|----------|--------|-----|
| **Inventing info** | README claims a feature that doesn't exist | Every claim must trace to a file, commit, or config |
| **Generic templates** | README doesn't reflect the actual architecture | Use Discovery Summary to tailor every section |
| **Ignoring history** | Changelog doesn't match git commits | Use `git log` between tags as the source of truth |
| **Hardcoded secrets** | API keys or passwords in README | Use env var names only; link to `.env.example` |
| **Stale badges** | CI badge points to wrong workflow | Verify badge URL matches actual workflow filename |
| **Manual PRs** | PR opened without review | Summarize changes first; let human open the PR |
| **Wrong language** | README in English for a pt-BR project | Match the language of existing documentation |

## Verification Checklist

- [ ] Discovery Summary was produced and confirmed before generation
- [ ] README includes all required sections based on available evidence
- [ ] No section contains invented or unverifiable information
- [ ] Tech stack versions match package manifests exactly
- [ ] Getting Started commands were verified against `scripts`/Makefile
- [ ] No secrets, API keys, or environment variable values are present
- [ ] CHANGELOG follows the "Keep a Changelog" format with all 6 categories
- [ ] CHANGELOG `[Unreleased]` section matches `git log` since last tag
- [ ] Version links point to valid compare/release URLs
- [ ] Mermaid diagrams (if any) have valid syntax
- [ ] Branch naming follows the project's convention
- [ ] Commit message follows Conventional Commits

## References

- [Keep a Changelog](https://keepachangelog.com/)
- [Semantic Versioning](https://semver.org/)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Shields.io](https://shields.io/) — badge generation
- [makeareadme.com](https://www.makeareadme.com/) — README best practices