Nmblr Readme

Quality Checks (scored)

<execution_instructions> When this skill is invoked, follow these steps based on the mode:

Mode: Audit (default — no flags)

Step 1: Gather project context

Read these files (skip any that don't exist):

• README.md
• CLAUDE.md
• Makefile (or justfile, taskfile.yml)
• .env.example (or env-example, .env.sample)
• package.json, go.mod, Cargo.toml, pyproject.toml (detect language)
• .claude/nmblr/config.yaml
• .claude/nmblr/install-manifest.json

Step 2: Check each section

For each item in the Required Sections checklist:

1. Search the README for the section heading (or equivalent)
2. If found, check that it has substantive content (not just a heading with placeholder text)
3. Score: Present (has content), Partial (heading exists but content is thin/placeholder), or Missing

Step 3: Run quality checks

For each item in the Quality Checks:

1. Q1-Q2: Grep README for <.*>, {.*}, placeholder patterns
2. Q3: Check which env file actually exists, compare to what README references
3. Q4: Extract file paths from README, verify each exists on disk
4. Q5: Extract make targets from README, verify each exists in Makefile
5. Q6: If ToC exists, verify each link matches a heading
6. Q7: Scan for patterns that look like secrets (base64 strings > 20 chars, sk-, pk_)
7. Q8: Check if intro has a "why" or "problem" statement (not just "X is a Y")
8. Q9: Check Quick Start has no hidden steps (references env setup before using env)

Step 4: Output audit report

## README Audit Report

**Overall Score:** {X}/18 sections present, {Y}/9 quality checks passing

### Section Checklist

| # | Section | Status | Notes |
|---|---------|--------|-------|
| 1 | Title + Description | ✅ Present | |
| 2 | Built With | ❌ Missing | |
| ... | ... | ... | ... |

### Quality Checks

| # | Check | Status | Notes |
|---|-------|--------|-------|
| Q1 | No placeholders | ✅ Pass | |
| Q2 | Real repo URL | ⚠️ Fail | Line 29: `<repo-url>` |
| ... | ... | ... | ... |

### Recommendations

1. **[High]** Add "Built With" section — ...
2. **[Medium]** Add Table of Contents — README is {N} lines
3. ...

Mode: Generate (--generate)

Step 1: Gather project context (same as audit Step 1)

Step 2: Detect project characteristics

From the gathered files, determine:

• Project name — from config.yaml, package.json, go.mod, or directory name
• Description — from CLAUDE.md overview or package.json description
• Language/framework — from go.mod, package.json, Cargo.toml, etc.
• Tech stack — from dependencies in manifest files
• Commands — from Makefile targets
• Env vars — from .env.example
• Repo URL — from git remote get-url origin
• Endpoints — grep for route registrations
• Doc types — from docs/ directory structure
• Deploy config — from .github/workflows/, .deployment/

Step 3: Ask user for missing context

Use AskUserQuestion for anything that can't be auto-detected:

• Project description / "why" statement (if not in CLAUDE.md)
• Target audience
• Any sections to skip

Step 4: Generate README

Produce a complete README following the gold-standard section order:

1. Title + Description (with "why") + Built With
2. Table of Contents
3. Features
4. Prerequisites
5. Quick Start (with real repo URL and env setup)
6. Project Structure
7. Development (Commands, Env Vars, Docker)
8. Architecture
9. Testing
10. API
11. Deployment
12. Contributing (detect nmblr workflow if config exists)
13. Security
14. Documentation
15. Troubleshooting (generate 3-5 based on detected tech)
16. Getting Help
17. License

Step 5: Write and verify

Write the generated README and run the audit checklist against it to confirm all sections are present and quality checks pass.

Mode: Fix (--fix)

Step 1: Run audit (Steps 1-4 from Audit mode)

Step 2: For each missing or partial section

• Missing sections: Generate the section content from project context (same detection as Generate mode) and append it in the correct position
• Partial sections: Leave existing content, add missing elements (e.g., add ToC if README > 150 lines)
• Quality failures: Fix automatically where possible (e.g., replace <repo-url> with actual repo URL from git remote)

Step 3: Do NOT rewrite existing content

The fix mode is additive — it fills gaps but respects what's already written. It should never rewrite a section that already has substantive content.

Step 4: Report changes made

List each change with before/after or addition summary. </execution_instructions>