configure-readme by laurigates/claude-plugins

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:

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

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"`

configure-readme