readme-write

Skill: readme-write

Base directory: .opencode/skill/readme-write

What I do

I update and create README.md files that follow best practices:

Choose the right badge set for the project type
Structure sections appropriately for the project
Include essential sections (Features, Getting Started, Usage, etc.)
Add contribution guidelines when applicable
Match documentation to the actual project structure

When to use me

Use this when:

Starting a new project and need a README scaffold
Improving an existing README for clarity and completeness
Preparing a project for open source release
Updating documentation after major features are added

How I work

Step 1: Analyze the project

I examine:

Project type (library, CLI, web app, TUI, etc.)
Programming language and framework
Hosting platform (GitHub, GitLab, Bitbucket, generic)
Existing files and structure
Package.json or similar config
Current documentation state
Check for existing README.md (preserve if updating)
Monorepo structure: Identify if this is a root README or a package-specific README in a monorepo (Lerna, Nx, Turborepo, Pnpm workspaces)

Step 2: Select appropriate sections

Choose sections based on project type:

For all projects:

Title with one-line description
Badges (CI, coverage, license, version)
Quick start example
Installation instructions
Link to full documentation

For libraries:

API documentation
Configuration options
Examples with code blocks
Requirements and dependencies

For CLI tools:

Installation (npm, brew, etc.)
Usage examples with commands
Available flags and options
Keyboard shortcuts

For web applications:

Screenshots or demo links
Deployment instructions
Environment variables
Backend requirements

For Monorepos:
Workspace overview (list of packages)
Root-level installation and build commands
Link to package-specific READMEs
Shared development requirements

Step 3: Detect configuration and add badges

First, detect what exists:

CI/CD: Check for .github/workflows/*.yml, .travis.yml, .circleci/, .gitlab-ci.yml
Package managers: Look for package.json, requirements.txt, Cargo.toml, go.mod, pom.xml
Quality: Check for .codecov.yml, codeclimate.yml, sonar-project.properties
Hosting: Detect GitHub (.github directory), GitLab (.gitlab-ci.yml), or generic

Badge URL patterns by platform:

GitHub: https://img.shields.io/github/actions/workflow/status/{org}/{repo}/{workflow}.yml
GitLab: https://img.shields.io/gitlab/pipeline/{org}/{repo}
Generics: Use shields.io/v2/ format

Select badges based on:

CI/CD: GitHub Actions, Travis, CircleCI, GitLab CI
Code quality: Codecov, CodeClimate, Sonar
Package: npm, PyPI, crates.io, Maven
Social: Discord, Slack, Matrix

Step 4: Include supplementary sections

Add based on project maturity:

Contributing guidelines (CONTRIBUTING.md)
Code of conduct (CODE_OF_CONDUCT.md)
Security policy (SECURITY.md)
Changelog (CHANGELOG.md or HISTORY.md)
License (LICENSE file)

Output format

I create a README.md file with:

Markdown syntax throughout
Proper heading hierarchy (H1 title, H2/H3 sections)
Code blocks with language annotations
Relative links to local resources
Badge images in standard sizes
Asset management: Reference images/logos from /assets or /docs/images using relative paths

Example output structure

# Project Name

Brief description (one line, under 80 characters)

[![CI](https://img.shields.io/github/actions/workflow/status/{org}/{repo}/test.yml)](https://github.com/{org}/{repo}/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://img.shields.io/npm/v/{project}.svg)](https://www.npmjs.com/package/{project})

## Features

- Feature 1 with brief description
- Feature 2 with brief description
- Feature 3 with brief description

## Getting Started

### Prerequisites

- Node.js 18+
- npm or yarn

### Installation

```bash
npm install project-name
```

Usage

# Basic usage
npm start --option

# Advanced usage
npm start --option --flag value

Documentation

See docs/ for detailed guides.

Contributing

Contributions welcome! See CONTRIBUTING.md.

License

MIT License - see LICENSE

Handling existing READMEs

When a README.md already exists:

Preserve user content: Keep custom sections, logos, project-specific content
Update structure: Add missing sections using the proper hierarchy
Modernize badges: Update badge URLs to current formats while preserving existing choices
Fix formatting: Correct markdown syntax, heading levels, and code blocks
Update dates: Refresh version info, last-updated dates

Never delete: User-added sections, custom formatting, project-specific troubleshooting guides, creative content

Always suggest/fix: Broken links, outdated badges, incorrect code blocks, missing installation instructions

Platform-specific badge formats

GitHub Actions:

[![CI](https://img.shields.io/github/actions/workflow/status/{org}/{repo}/{workflow}.yml)](https://github.com/{org}/{repo}/actions)

GitLab CI:

[![CI](https://img.shields.io/gitlab/pipeline/{org}/{repo}])(https://gitlab.com/{org}/{repo}/pipelines)

npm:

[![npm](https://img.shields.io/npm/v/{package})](https://www.npmjs.com/package/{package})

PyPI:

[![PyPI](https://img.shields.io/pypi/v/{package})](https://pypi.org/project/{package}/)

Crates.io:

[![crates.io](https://img.shields.io/crates/v/{package})](https://crates.io/crates/{package})

Validation checklist

Before finalizing, I ensure:

Safety Notice

Copy this and send it to your AI assistant to learn