Help us improve
Share bugs, ideas, or general feedback.
From shavakan-commands
Generate/update condensed developer README for project usage and contribution
npx claudepluginhub shavakan/claude-marketplace --plugin shavakan-commandsHow this command is triggered — by the user, by Claude, or both
Slash command
/shavakan-commands:docs-readmeThe summary Claude sees in its command listing — used to decide when to auto-load this command
# README Generator Create/update README.md in project root. **Constraints: < 200 lines, scannable in 30 seconds, technical tone (no marketing).** ## Additional Instructions $ARGUMENTS --- ## Analysis Phase Check files in order, record findings: 1. `flake.nix` → Nix flake present (Y/N) 2. `.envrc` + `.envrc.example` → direnv present (Y/N) 3. `Makefile` → Make targets available (Y/N) 4. `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` → Language ecosystem 5. Existing `README.md` → Preserve badges, screenshots, custom sections 6. Entry points → `main.py`, `index.ts`, `cmd/mai...
/generate-readmeGenerates README.md by analyzing project files, detecting language/framework, extracting metadata/installation/usage, and adding badges/TOC.
/readme-makerAnalyzes project structure and generates a professional README.md with quick start, feature documentation, and contributing guidelines. Also supports --style, --output, and --dry-run flags.
/update-readmeUpdates or creates README.md reflecting current project state with installation, quick start, usage, development sections, badges, and verified examples. Shows diff if updating.
Share bugs, ideas, or general feedback.
Create/update README.md in project root. Constraints: < 200 lines, scannable in 30 seconds, technical tone (no marketing).
$ARGUMENTS
Check files in order, record findings:
flake.nix → Nix flake present (Y/N).envrc + .envrc.example → direnv present (Y/N)Makefile → Make targets available (Y/N)package.json / pyproject.toml / go.mod / Cargo.toml → Language ecosystemREADME.md → Preserve badges, screenshots, custom sectionsmain.py, index.ts, cmd/main.go, etcSelect primary build interface based on presence:
| Priority | System | When | Commands |
|---|---|---|---|
| 1 | Nix | flake.nix exists | nix develop, nix build, nix run |
| 2 | Make | Makefile exists | make install, make test, make build |
| 3 | Package manager | package.json / Cargo.toml | npm install, cargo build |
| 4 | Direct | None above | python -m, go run, etc |
If multiple exist: Use highest priority as primary, mention others as alternatives.
If .envrc exists:
cp .envrc.example .envrc && direnv allow.envrc.example for variablesIf no direnv:
.env files or manual export commandsRequired sections (generate in order):
# [Project Name]
> [Single sentence: does X for Y users]
Prerequisites: List tools with versions. Omit language version if Nix manages it. Include Nix/direnv if detected.
Install: Commands to get dependencies. Prioritize by build system table above.
Run: Command to start/execute. Include port/URL for web apps.
Test: Command to run tests. Use nix flake check if available.
Tree diagram of key directories with inline comments:
src/
core/ # Business logic
api/ # Endpoints
tests/ # Test suite
Setup: Additional dev steps (direnv, pre-commit hooks, etc)
Build/Lint/Format: Commands using primary build system
Common tasks: 2-3 bullet points for frequent operations
Architecture: 2-3 sentences on design decisions and tradeoffs. Include if non-obvious.
Configuration: Env vars with descriptions. Required vs optional. Include if app needs config.
Deployment: Deploy command or link. Include for deployable apps.
Contributing: Link to CONTRIBUTING.md or inline if < 5 rules.
License: License type. Include if LICENSE file exists.
Command syntax:
bash\nnpm run dev\n"npm run dev"Section length: Each section < 15 lines. Link to detailed docs if longer.
Style: Technical, direct. Explain WHY for architecture, not WHAT code does. No "easy", "simple", "just".
Preservation: Keep existing badges, screenshots, unique sections from old README.
| Type | Adaptations |
|---|---|
| CLI tool | Add "Usage" with examples, omit "Running" |
| Library | Add "Installation" + "Usage" with API examples, omit "Running" |
| Web app | Include PORT/URL in "Run", add "Deployment" |
| Monorepo | Show workspace structure, document per-package commands |
| Nix multi-output | Add nix flake show output, document available apps/packages |
README.mdNo build system found: Use direct language commands (python, go run, etc) and warn in preview.
Nix without devShell: Use nix-shell or nix develop with warnings about flake completeness.
Multiple entry points: List all in "Run" section with descriptions.
Secrets in .envrc: Never read actual .envrc, only .envrc.example. Remind about .gitignore.
Input: "Generate README"
Analysis:
Build priority: Nix (priority 1), mention Make as fallback
Preview: "Next.js web app with Nix flake and direnv. README uses nix run for primary interface, notes make commands as alternative. Includes .envrc.example setup. ~90 lines. Approve?"
Output: README.md with Nix-first commands, direnv setup, project structure showing pages/ and components/, development section with nix build and nix flake check.