configure-readme

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:

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:

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:

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

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