Configure Readme

When to Use This Skill

Context

• Project root: !pwd
• Project name: !basename $(pwd)
• README exists: !find . -maxdepth 1 -name 'README.md'
• Package files: !find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' \)
• Git remotes: !git remote -v
• License file: !find . -maxdepth 1 -name 'LICENSE*'
• Assets directory: !find . -maxdepth 2 -type d \( -name 'assets' -o -name 'public' -o -name 'images' \)
• Logo files: !find . -maxdepth 3 -type f \( -name 'logo*' -o -name 'icon*' \)

Parameters

Parse from command arguments:

• --check-only: Report README compliance status without modifications (CI/CD mode)
• --fix: Apply fixes automatically without prompting
• --style <minimal|standard|detailed>: README detail level (default: standard)
• --badges <shields|custom>: Badge style preference (default: shields)
• --no-logo: Skip logo section even if assets exist

Style Levels:

• minimal: Title, description, badges, basic install/usage
• standard: Logo, badges, features, tech stack, getting started, license (recommended)
• detailed: All of standard plus: architecture diagram, API reference, contributing guide, changelog link

Execution

Execute this README configuration workflow:

Step 1: Detect project metadata

Read project metadata from the detected package files:

1. package.json (JavaScript/TypeScript): Extract name, description, version, license, repository, keywords 2. pyproject.toml (Python): Extract project name, description, version, license, keywords, URLs 3. Cargo.toml (Rust): Extract package name, description, version, license, repository, keywords 4. go.mod (Go): Extract module path for owner/repo

Fallback detection when no package file matches:

• Project name: directory name
• Description: first line of existing README or ask user
• Repository: git remote URL
• License: LICENSE file content

For detailed package file format examples, see REFERENCE.md.

Step 2: Analyze current README state

Check existing README.md for these sections:

• [ ] Logo/icon present (centered image at top)
• [ ] Project title (h1)
• [ ] Description/tagline
• [ ] Badges row (license, version, CI status, coverage)
• [ ] Features section
• [ ] Tech Stack section
• [ ] Prerequisites section
• [ ] Installation instructions
• [ ] Usage examples
• [ ] Project structure
• [ ] Contributing guidelines
• [ ] License section

Discover logo/icon assets in common locations:

• assets/logo.png, assets/icon.png, assets/logo.svg
• public/logo.png, public/icon.svg
• images/logo.png, docs/assets/logo.png
• .github/logo.png, .github/images/logo.png

Step 3: Generate compliance report

Print a section-by-section compliance report showing PASS/MISSING/PARTIAL status for each README section. Include content quality checks (code examples, command correctness, link validity).

If --check-only is set, stop here.

For the compliance report format, see REFERENCE.md.

Step 4: Apply configuration (if --fix or user confirms)

Generate README.md following the standard template structure:

1. Centered logo section (if assets exist and --no-logo not set) 2. Project title and tagline 3. Badge row with shields.io URLs 4. Features section with key highlights 5. Tech Stack table 6. Getting Started (prerequisites, installation, usage) 7. Project Structure 8. Development commands 9. Contributing section 10. License section

For the full README template and badge URL patterns, see REFERENCE.md.

Step 5: Handle logo and assets

If no logo exists but user wants one:

1. Check for existing assets in standard locations 2. Suggest creating a simple text-based placeholder or using emoji heading 3. Create assets directory if needed: mkdir -p assets 4. Suggest tools: Shields.io for custom badges, Simple Icons for technology icons

Step 6: Detect project commands

Auto-detect project commands based on package manager/build tool:

Step 7: Generate project structure

Run tree -L 2 -I 'node_modules|target|__pycache__|.git|dist|build' --dirsfirst to generate accurate project structure. Skip common generated directories (node_modules, vendor, target, dist, build, __pycache__, .pytest_cache, .git, .venv, venv).

Step 8: Update standards tracking

Update .project-standards.yaml:

components:
  readme: "2025.1"
  readme_style: "[minimal|standard|detailed]"
  readme_has_logo: true|false
  readme_badges: ["license", "stars", "ci", "version"]

Step 9: Validate generated README

After generating README, validate:

1. Check for markdown syntax errors 2. Verify all links are accessible (warn only) 3. Ensure shields.io URLs are correctly formatted 4. Verify logo/image paths exist

Step 10: Report configuration results

Print a summary of changes made, the README location, and recommended next steps (customize feature descriptions, add logo, run other configure commands).

For the results report format, see REFERENCE.md.

When --style detailed is specified, also include architecture section with mermaid diagram, API reference link, and changelog link. For detailed style templates, see REFERENCE.md.

Output

Provide: 1. Compliance report with section-by-section status 2. Generated or updated README.md content 3. List of detected project metadata 4. Suggestions for improvement (logo, more features, etc.)

Agentic Optimizations

See Also

• /configure:docs - Configure code documentation standards
• /configure:github-pages - Set up documentation hosting
• /configure:all - Run all compliance checks
• readme-standards skill for README templates and examples

configure-readme Reference

Package File Format Examples

package.json (JavaScript/TypeScript)

{
  "name": "project-name",
  "description": "Project description",
  "version": "1.0.0",
  "license": "MIT",
  "repository": { "url": "github:owner/repo" },
  "keywords": ["keyword1", "keyword2"]
}

pyproject.toml (Python)

[project]
name = "project-name"
description = "Project description"
version = "1.0.0"
license = "MIT"
keywords = ["keyword1", "keyword2"]

[project.urls]
Repository = "https://github.com/owner/repo"

Cargo.toml (Rust)

[package]
name = "project-name"
description = "Project description"
version = "1.0.0"
license = "MIT"
repository = "https://github.com/owner/repo"
keywords = ["keyword1", "keyword2"]

go.mod (Go)

module github.com/owner/repo

Compliance Report Format

README.md Compliance Report
===========================
Project: [name]
Style Level: [minimal|standard|detailed]

Structure:
  Logo/Icon              [PASS | MISSING | N/A (no assets)]
  Title                  [PASS | MISSING]
  Description            [PASS | MISSING | TOO SHORT]
  Badges                 [PASS | PARTIAL | MISSING]
  Features               [PASS | MISSING]
  Tech Stack             [PASS | MISSING]
  Getting Started        [PASS | INCOMPLETE | MISSING]
  Project Structure      [PASS | MISSING | N/A (small project)]
  License                [PASS | MISSING]

Content Quality:
  Has code examples      [YES | NO]
  Commands are correct   [YES | OUTDATED]
  Links are valid        [YES | BROKEN LINKS]

Overall: [X issues found]

README Template (Standard Style)

<div align="center">

<img src="assets/logo.png" alt="PROJECT_NAME Logo" width="128" height="128">

# PROJECT_NAME

**TAGLINE_DESCRIPTION**

[![License](https://img.shields.io/github/license/OWNER/REPO)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/OWNER/REPO)](https://github.com/OWNER/REPO/stargazers)
[![CI](https://img.shields.io/github/actions/workflow/status/OWNER/REPO/ci.yml?branch=main&label=CI)](https://github.com/OWNER/REPO/actions)
[![RUNTIME_BADGE](RUNTIME_BADGE_URL)]()

</div>

## Features

- **Feature 1** - Description of the first key feature
- **Feature 2** - Description of the second key feature
- **Feature 3** - Description of the third key feature
- **Feature 4** - Description of the fourth key feature

## Tech Stack

| Category | Technology |
|----------|------------|
| Runtime | Node.js / Bun / Python / Rust |
| Framework | Express / Fastify / FastAPI / Axum |
| Database | PostgreSQL / SQLite / MongoDB |
| Testing | Vitest / pytest / cargo-nextest |

## Getting Started

### Prerequisites

- [Prerequisite 1](link) >= version
- [Prerequisite 2](link) >= version

### Installation

Clone the repository

git clone https://github.com/OWNER/REPO.git cd REPO

Install dependencies

INSTALL_COMMAND

Run the application

RUN_COMMAND

### Usage

Example command

EXAMPLE_COMMAND

## Project Structure

PROJECT_NAME/ ├── src/ # Source code │ ├── components/ # UI components (if applicable) │ └── services/ # Business logic ├── tests/ # Test files ├── docs/ # Documentation └── README.md

## Development

Run tests

TEST_COMMAND

Run linter

LINT_COMMAND

Build for production

BUILD_COMMAND

## Contributing

Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting a PR.

## License

This project is licensed under the [LICENSE_TYPE](LICENSE) license.

Badge URL Patterns

Standard Shields.io Badges

Runtime/Tech Badges

Placeholder Logo

When no logo exists:

<div align="center">
<h1>PROJECT_NAME</h1>
</div>

Tools for creating logos:

• Shields.io for custom badges
• Simple Icons for technology icons
• AI image generators for custom logos

Results Report Format

README.md Compliance Report (After Configuration)
=================================================
Project: [name]
Style Level: [minimal|standard|detailed]

Changes Made:
  Added centered logo section
  Generated badge row (license, stars, CI)
  Created Features section with 4 highlights
  Added Tech Stack table
  Generated Getting Started with correct commands
  Created Project Structure from actual layout
  Added License section

README Location: ./README.md
Preview: Open in VS Code or view on GitHub

Next Steps:
  - Review and customize feature descriptions
  - Add a logo image to assets/ (optional)
  - Run /configure:github-pages to publish documentation
  - Consider adding CONTRIBUTING.md and CHANGELOG.md

Detailed Style Additions

When --style detailed is specified, also include:

Architecture Section

## Architecture

graph TD A[Client] --> B[API Gateway] B --> C[Service Layer] C --> D[Database]

API Reference Link

## API Reference

See the [API Documentation](docs/api.md) for detailed endpoint information.

Changelog Link

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.