Write README
Scope: $ARGUMENTS
Generate or update a README.md following scope-specific best practices.
Phase 1: Detect Scope
Parse $ARGUMENTS to determine scope:
repo (default) — README.md for a code repository in the current directoryrepo <owner/repo> — README.md for a specific remote repositoryaccount <username> — profile README for a GitHub user (<username>/<username>/README.md)org <orgname> — organization profile README (.github/profile/README.md)
If no scope is given, default to repo for the current working directory.
Phase 2: Gather Context
For repo
- Read existing README.md (if any)
- Detect project type:
action.yml / action.yaml exists → GitHub Actionpyproject.toml / setup.py → Python librarypackage.json → Node.js/TypeScriptCargo.toml → Rustgo.mod → Go
- Read project manifest for name, version, description, license
- Scan source tree:
src/, lib/, main entry points
- Read LICENSE file
- Check for existing docs: CONTRIBUTING.md, AGENTS.md, docs/
For account
gh api users/<username> — bio, company, location, bloggh repo list <username> --limit 30 --json name,description,stargazerCount,primaryLanguage — repos sorted by stars- Read existing
<username>/<username>/README.md if it exists
- Identify top 3-5 repos by stars or recent activity
For org
gh api orgs/<orgname> — description, blog, locationgh repo list <orgname> --limit 50 --json name,description,isPrivate,stargazerCount,primaryLanguage — public repos- Read existing
.github/profile/README.md or .github/readme.md
- Group repos by domain/purpose
- Identify pinned repos if any
Phase 3: Apply Template
See references/readme-templates.md for the four template snippets and per-scope conventions (GitHub Action, Library/Application, Account, Organization). Repo READMEs follow the qte77 doc-structure canon: value-first order Hero → Badges → What → How → Why → Refs → License → tail; badges License → Version → CI (static blue / native status, Version linked to CHANGELOG.md).
Pick the template matching the scope detected in Phase 1 and the project type detected in Phase 2.
Phase 4: Generate
- Draft the README applying the appropriate template
- Verify all links resolve
- Present the draft to the user for review
- Write the file after user approval
Rules
- Never add content the project doesn't have
- Keep descriptions factual — pull from existing docs, manifests, and code
- Don't add emojis unless the user requests them
- Prefer brevity — every sentence should earn its place
- For org READMEs: omit private repos unless the user explicitly asks
- License file is always
LICENSE (never LICENSE.md)
- Repo READMEs derive from the qte77 doc-structure canon — never invent a divergent structure
1---2name: writing-readme3description: Generate or update README.md files across three scopes — repo (with project-type detection), account (GitHub user profile), and org (organization profile). Use when creating, updating, or aligning a README to org conventions.4---56# Write README78**Scope**: $ARGUMENTS910Generate or update a README.md following scope-specific best practices.1112## Phase 1: Detect Scope1314Parse `$ARGUMENTS` to determine scope:1516- `repo` (default) — README.md for a code repository in the current directory17- `repo <owner/repo>` — README.md for a specific remote repository18- `account <username>` — profile README for a GitHub user (`<username>/<username>/README.md`)19- `org <orgname>` — organization profile README (`.github/profile/README.md`)2021If no scope is given, default to `repo` for the current working directory.2223## Phase 2: Gather Context2425### For `repo`26271. Read existing README.md (if any)282. Detect project type:29 - `action.yml` / `action.yaml` exists → GitHub Action30 - `pyproject.toml` / `setup.py` → Python library31 - `package.json` → Node.js/TypeScript32 - `Cargo.toml` → Rust33 - `go.mod` → Go343. Read project manifest for name, version, description, license354. Scan source tree: `src/`, `lib/`, main entry points365. Read LICENSE file376. Check for existing docs: CONTRIBUTING.md, AGENTS.md, docs/3839### For `account`40411. `gh api users/<username>` — bio, company, location, blog422. `gh repo list <username> --limit 30 --json name,description,stargazerCount,primaryLanguage` — repos sorted by stars433. Read existing `<username>/<username>/README.md` if it exists444. Identify top 3-5 repos by stars or recent activity4546### For `org`47481. `gh api orgs/<orgname>` — description, blog, location492. `gh repo list <orgname> --limit 50 --json name,description,isPrivate,stargazerCount,primaryLanguage` — public repos503. Read existing `.github/profile/README.md` or `.github/readme.md`514. Group repos by domain/purpose525. Identify pinned repos if any5354## Phase 3: Apply Template5556See `references/readme-templates.md` for the four template snippets and per-scope conventions (GitHub Action, Library/Application, Account, Organization). Repo READMEs follow the [qte77 doc-structure canon](https://github.com/qte77/qte77/blob/main/docs/doc-structure.md): value-first order Hero → Badges → What → How → Why → Refs → License → tail; badges License → Version → CI (static `blue` / native status, Version linked to `CHANGELOG.md`).5758Pick the template matching the scope detected in Phase 1 and the project type detected in Phase 2.5960## Phase 4: Generate61621. Draft the README applying the appropriate template632. Verify all links resolve643. Present the draft to the user for review654. Write the file after user approval6667## Rules6869- Never add content the project doesn't have70- Keep descriptions factual — pull from existing docs, manifests, and code71- Don't add emojis unless the user requests them72- Prefer brevity — every sentence should earn its place73- For org READMEs: omit private repos unless the user explicitly asks74- License file is always `LICENSE` (never `LICENSE.md`)75- Repo READMEs derive from the qte77 doc-structure canon — never invent a divergent structure
qte77