create-readme · diff
v1.0.0 to v1.1.0
259 added, 43 removed. Audit A to A.
---
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, and alignment with Keep a Changelog and SemVer standards. Do NOT use for API-reference docs (use dedicated doc tooling) or for licenses/governance documents.
+ 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.0.0"
+ 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.
+ 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**: Root directory tree and top-level files.
- - **Stack**: `package.json`, `*.csproj`, `pom.xml`, `pyproject.toml`, `Dockerfile`, etc.
- - **CI/CD**: `.github/workflows/` and pipeline definitions.
- - **History**: `git log --oneline -n 50` to identify recent features and fixes.
- - **Existing Docs**: Current `README.md` and `CHANGELOG.md`.
- **Requirement**: Output a "Discovery Summary" containing Stack, Architecture, CI/CD, and identified gaps before proceeding to generation.
+ **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:
- 1. **Title & Badges**: Project name and detectable status badges.
- 2. **Project Description**: Rich functional and strategic overview.
- 3. **Repository Structure**: Hierarchical tree with short descriptions per item.
- 4. **Tech Stack**: Explicit list of languages, frameworks, and cloud services.
- 5. **Architecture**: Layers and patterns (e.g., Clean Architecture, DDD).
- 6. **System Flow**: Mermaid diagrams or textual flow descriptions.
- 7. **Getting Started**: Prerequisites, env vars, and run commands.
- 8. **Tests & Coverage**: Execution commands and coverage metrics.
- 9. **Business & Technical Views**: Strategic goals vs. implementation details.
- 10. **License & Status**: License type and current project state.
- 11. **Links**: Internal references and link to `CHANGELOG.md`.
- **Rules**:
- - Reuse existing content where applicable.
- - Only include sections where concrete evidence exists.
- - Default to English (en-us) to match the skill catalog; only use another language if the repository's existing documentation is consistently written in that language.
+ 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: `[](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:
- - **Structure**: Maintain a `[Unreleased]` section at the top.
- - **Categories**: Use `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security`.
- - **Source**: Populate categories by analyzing recent git commits.
- - **Linking**: Link version numbers to tags or compare URLs.
+ #### 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
- 1. **Branching**: Create a dedicated branch `feature/{YYYYMMDD}-readme-changelog`.
- 2. **Linting**: Run a Markdown linter if available.
- 3. **Commit**: Use Conventional Commits: `docs(readme): update README and CHANGELOG`.
- 4. **Reporting**: Provide a summary of changes; do not open the PR automatically.
+ #### 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
- - **Inventing Info**: Stating a feature exists without finding it in the code.
- - **Generic Templates**: Using a "one size fits all" README that doesn't reflect the actual architecture.
- - **Ignoring History**: Creating a changelog that doesn't match the git commit history.
- - **Manual PRs**: Opening the PR without summarizing the changes for the human reviewer.
- ## Verification
- - [ ] Discovery Summary was produced before generation.
- - [ ] README includes all required sections based on available evidence.
- - [ ] CHANGELOG follows the "Keep a Changelog" format.
- - [ ] No secrets or credentials were accidentally included.
- - [ ] Branch naming follows the project's convention.
+ | 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