When to Use This Skill

Use this skill when... Use another approach when...

Creating a README.md for a new project from scratch Editing specific README content — use direct file editing

Auditing an existing README for missing sections (badges, install, structure) Writing detailed API documentation — use /configure:docs

Standardizing README format across multiple projects Creating GitHub Pages documentation site — use /configure:github-pages

Adding shields.io badges, tech stack table, or project structure section Writing a changelog — use release-please automation via conventional commits

Ensuring README includes correct install/build/test commands for the detected stack Only need to update a single section — edit the file directly

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:

• package.json (JavaScript/TypeScript): Extract name, description, version, license, repository, keywords

• pyproject.toml (Python): Extract project name, description, version, license, keywords, URLs

• Cargo.toml (Rust): Extract package name, description, version, license, repository, keywords

• 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:

• Centered logo section (if assets exist and --no-logo not set)

• Project title and tagline

• Badge row with shields.io URLs

• Features section with key highlights

• Tech Stack table

• Getting Started (prerequisites, installation, usage)

• Project Structure

• Development commands

• Contributing section

• 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:

• Check for existing assets in standard locations

• Suggest creating a simple text-based placeholder or using emoji heading

• Create assets directory if needed: mkdir -p assets

• 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:

Package Manager Install Run Test Build

npm/bun (package.json) Read scripts from package.json npm run dev

npm test

npm run build

uv/poetry (pyproject.toml) uv sync / poetry install

uv run python -m pkg

uv run pytest

cargo (Cargo.toml) cargo build

cargo run

cargo test

cargo build --release

go (go.mod) go build

go run .

go test ./...

go build

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:

• Check for markdown syntax errors

• Verify all links are accessible (warn only)

• Ensure shields.io URLs are correctly formatted

• 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:

• Compliance report with section-by-section status

• Generated or updated README.md content

• List of detected project metadata

• Suggestions for improvement (logo, more features, etc.)

Agentic Optimizations

Context Command

Quick compliance check /configure:readme --check-only

Auto-fix all issues /configure:readme --fix

Minimal README /configure:readme --fix --style minimal

Full detailed README /configure:readme --fix --style detailed

Generate project tree tree -L 2 -I 'node_modules|target|pycache|.git|dist|build' --dirsfirst

Check README exists test -f README.md && echo "EXISTS" || echo "MISSING"

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