diff --git a/docs/README.skills.md b/docs/README.skills.md index 24473fa6f4..1be1bb2dd5 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -294,6 +294,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [next-intl-add-language](../skills/next-intl-add-language/SKILL.md)
`gh skills install github/awesome-copilot next-intl-add-language` | Add new language to a Next.js + next-intl application | None | | [noob-mode](../skills/noob-mode/SKILL.md)
`gh skills install github/awesome-copilot noob-mode` | Plain-English translation layer for non-technical Copilot CLI users. Translates every approval prompt, error message, and technical output into clear, jargon-free English with color-coded risk indicators. | `references/examples.md`
`references/glossary.md` | | [nuget-manager](../skills/nuget-manager/SKILL.md)
`gh skills install github/awesome-copilot nuget-manager` | Manage NuGet packages in .NET projects/solutions. Use this skill when adding, removing, or updating NuGet package versions. It enforces using `dotnet` CLI for package management and provides strict procedures for direct file edits only when updating versions. | None | +| [nuxt-style-readme](../skills/nuxt-style-readme/SKILL.md)
`gh skills install github/awesome-copilot nuxt-style-readme` | Writes and refines a repository's README.md in a concise, Nuxt-inspired documentation style: sections chosen from what the repository actually contains, scannable feature bullets, emoji-anchored headings, and a banner, badges, and docs links only when the repository provides them. Use this skill when the user wants a README created, rewritten, restructured, tightened, polished, or brought up to date after the code changed, when they want a project's front page documentation improved or made consistent with their other repositories, or when they point you at a repo and ask what its README should say, even if they never use the word "README". Applies to repositories in any language or framework. Do not use it for changelogs, release notes, API reference, contributing guides, standalone documentation pages, or marketing copy. | `assets/readme-template.md`
`references/section-rules.md`
`references/style-guide.md` | | [onboard-context-matic](../skills/onboard-context-matic/SKILL.md)
`gh skills install github/awesome-copilot onboard-context-matic` | Interactive onboarding tour for the context-matic MCP server. Walks the user through what the server does, shows all available APIs, lets them pick one to explore, explains it in their project language, demonstrates model_search and endpoint_search live, and ends with a menu of things the user can ask the agent to do. USE FOR: first-time setup; "what can this MCP do?"; "show me the available APIs"; "onboard me"; "how do I use the context-matic server"; "give me a tour". DO NOT USE FOR: actually integrating an API end-to-end (use integrate-context-matic instead). | None | | [oo-component-documentation](../skills/oo-component-documentation/SKILL.md)
`gh skills install github/awesome-copilot oo-component-documentation` | Create or update standardized object-oriented component documentation using a shared template plus mode-specific guidance for new and existing docs. | `assets/documentation-template.md`
`references/create-mode.md`
`references/update-mode.md` | | [openapi-to-application-code](../skills/openapi-to-application-code/SKILL.md)
`gh skills install github/awesome-copilot openapi-to-application-code` | Generate a complete, production-ready application from an OpenAPI specification | None | diff --git a/skills/nuxt-style-readme/SKILL.md b/skills/nuxt-style-readme/SKILL.md new file mode 100644 index 0000000000..0d490c438a --- /dev/null +++ b/skills/nuxt-style-readme/SKILL.md @@ -0,0 +1,135 @@ +--- +name: nuxt-style-readme +description: 'Writes and refines a repository''s README.md in a concise, Nuxt-inspired documentation style: sections chosen from what the repository actually contains, scannable feature bullets, emoji-anchored headings, and a banner, badges, and docs links only when the repository provides them. Use this skill when the user wants a README created, rewritten, restructured, tightened, polished, or brought up to date after the code changed, when they want a project''s front page documentation improved or made consistent with their other repositories, or when they point you at a repo and ask what its README should say, even if they never use the word "README". Applies to repositories in any language or framework. Do not use it for changelogs, release notes, API reference, contributing guides, standalone documentation pages, or marketing copy.' +--- + +# Nuxt-style README + +Produce a README that carries a new reader from "what is this" to "it works on my machine" with nothing in the way. + +The style is descended from the Nuxt ecosystem: short introduction, feature-oriented presentation, fast path to first success, clear next steps, minimal ceremony. Two things separate it from a generic README. Sections are chosen from evidence in the repository rather than from a fixed template, and every claim traces back to a file you actually read. + +## Non-negotiables + +These hold on every run, for every repository. + +- **Evidence or omission.** Every command, package name, environment variable, option, path, version requirement, and capability claim must come from a file you read in this repository. If you cannot point at the source, leave it out. +- **Chrome is found, never fabricated.** A banner appears only when the repository carries the asset or the user provides one. A badge block appears only for a published package with a release path, or when the user supplies badges, and every badge states a fact the repository proves. A Documentation or Playground bullet appears only when the target exists. Never invent an asset path, a badge, or a link. +- **No invented imagery.** Never fabricate a screenshot, logo, or diagram. Imagery that genuinely explains something stays unless the user asks for its removal. +- **`## Features` takes no emoji.** Neither does `## Background` or `## Why?`. Every other user-facing H2 takes one. +- **Every feature bullet takes an emoji.** See the format below. +- **Sections are earned.** A section exists because the repository gives you something real to put in it. Never add one to look thorough. +- **No em dashes or en dashes as punctuation, and no semicolons in prose.** Rewrite the sentence. This does not apply to code, commands, paths, package names, URLs, versions, or quoted material, where the character is part of the content. + +## Workflow + +### 1. Read the repository + +Do not work from the existing README alone. It is a claim about the project, not evidence. Read it first so you know what it asserts, then carry a line forward only after you have verified it against a file. + +If it carries generator markers such as ``, ``, or ``, a script owns that block. Leave the markers and everything between them untouched, even when the content breaks a rule here, and tell the user instead. + +Read what materially describes how the project works, which usually includes package manifests and lockfiles, workspace configuration, entry points (CLI, application, or public API), source that implements the headline behavior, configuration files and schemas, environment variable definitions, scripts, tests, examples and playgrounds, CI workflows, release configuration, the license file, and any existing contributing or architecture documentation. + +Read the scripts block before you document a single command. Inventing `npm test` for a repository that uses `bun test` is the most common way this task fails. + +The lockfile picks the package manager for every command run inside the repository. `bun.lock` or `bun.lockb` means `bun`, `pnpm-lock.yaml` means `pnpm`, `yarn.lock` means `yarn`, `package-lock.json` means `npm`, and a `packageManager` field in the manifest overrides all of them. The same logic applies outside JavaScript, where `uv.lock` means uv, `poetry.lock` means Poetry, and `Gemfile.lock` means Bundler. The install line a consumer runs against a published package is not bound by this. + +Use version control history only to settle a specific question, such as whether documented behavior is current. Stop once the question is answered. + +You are answering: what does this do, who is it for, what is the shortest path to it working, how is it normally used, what can be configured, what are its real constraints, how do contributors work on it, and what is its license. + +### 2. Decide the sections + +Read `references/section-rules.md` now, before choosing an outline. It gives an inclusion test for every optional section and the default ordering. + +Resolve ordinary choices yourself from repository evidence and the rules in this skill. Do not ask the user which sections they want. + +### 3. Draft + +Read `references/style-guide.md` before writing prose. It covers opening chrome formats, heading and emoji conventions, tables, code blocks, diagrams, linking, tone, and license wording. + +Read `assets/readme-template.md` only when you are building a README from nothing or substantially restructuring one. It is a skeleton of optional parts, not a form to fill in. Skip it when you are making a targeted revision. + +When refining an existing README, preserve what already works. A strong README should receive small, surgical edits, not a rewrite. Chrome follows the inclusion tests, not the incumbent README: strip badges stating unproven facts, banners with no committed asset, and Documentation or Playground bullets with dead targets, and say so in your summary. Keep the chrome the repository earns, normalized to the format in `references/style-guide.md`. + +### 4. Verify + +Before you finish, check each of these against the repository: + +- Every command appears in the manifest scripts, a CI workflow, or documented tooling. +- Package names, import paths, and subpath exports match the manifest exactly. +- Version and runtime requirements match what the manifest or CI declares. +- Relative links resolve to files that exist. Prefer `./path` form. +- The banner asset exists at the referenced path, every badge states a proved fact, and the Documentation and Playground bullets resolve. +- The license statement matches the LICENSE file, or the manifest `license` field when there is no LICENSE file. Never infer a license, and never write MIT because it is common. +- No section is empty, and no section restates one above it. +- Markdown renders: fenced blocks closed, tables aligned, alert syntax exact. +- Reread once end to end for flow and concision, and cut anything a reader could infer. + +If you used any GitHub alert, confirm the current syntax, the supported types, and the usage limits against `https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax`. `references/style-guide.md` records what that page said when this skill was written, which is a starting point and not a substitute for checking. If you cannot reach the page, use the recorded rules and say plainly that live verification was unavailable. Never claim you verified something you did not. + +Review the final diff. The only file that should have changed is the README, plus anything the user explicitly asked for. + +## The opening + +The first elements, in this order, with nothing before them: + +1. Banner image, only when the repository provides the asset, linked to the documentation site when one exists. +2. Badge block, only badges whose facts the repository proves, in the format from `references/style-guide.md`. +3. `# Title`. Use the exact package name for a publishable package, otherwise a readable product name. +4. One sentence saying what the project is. Concrete, no marketing. +5. Documentation and Playground bullets, only when the targets exist, in the format from `references/style-guide.md`. +6. At most one GitHub alert, and only when a legal, safety, or scope caveat changes how someone should use the project. +7. The first H2 the repository earns, in the order from `references/section-rules.md`. Usually that is `## Features`. + +A leading alert can carry the one-sentence description itself when the caveat and the description are the same thought, which is common for private or license-constrained packages. + +## Feature bullets + +```markdown +- ๐ŸŽฏ **Feature name:** One sentence stating the concrete capability or benefit. +``` + +One emoji chosen for that specific feature, with no emoji appearing twice in the list, then a bold label of one to four words in sentence case, a colon inside the bold, then one full sentence. The label is a noun or adjective phrase naming the capability, and it may be a link when the feature has a canonical page, such as the technology it wraps or its own docs guide, written `**[Label](url):**` with the colon inside the bold and outside the link. Link a label only where the target genuinely helps, not on every bullet. The sentence is present tense, leads with an active verb, makes one primary claim, ends with a period, and stays as short as accuracy allows. Aim for the whole bullet to render on one line, which usually means a description of eight to fifteen words, and run longer only when precision demands it. No dangling fragments: "Uses chezmoi in symlink mode with Go templates for per-machine configuration", not "chezmoi in symlink mode, Go templates for per-machine configs". + +Lead with the capability and order the list from defining to supporting. Name what the project does that a reader could not assume, with the specific verb rather than the generic one, and write "Supports" only when compatibility itself is the feature. State whether behavior is automatic or opt-in, and do not word configuration-dependent behavior as a guarantee. Round a count that grows with the project down to a stable floor, 100+ rather than 123, so the sentence stays true as the project moves. A count that is itself the fact, such as a default value, or one small enough that the list could name each member, stays exact. Skip "powerful", "modern", "blazing fast", and "easy to use" unless the repository proves the claim, in which case state the proof instead of the adjective. + +Aim for about four to fifteen bullets, past fifteen only when the project genuinely has more important features than that, and below four when it genuinely has fewer, since two nameable capabilities still earn the section. `Features` is a summary, not an inventory, so implementation detail belongs in a later section or nowhere. + +## Asking the user + +Prefer a sensible default over a question. Resolve decisions in this order: repository evidence, then this skill's rules, then general technical writing judgment. + +Ask only when a decision materially changes the README and evidence cannot settle it. That means ambiguous project positioning, two genuinely competing primary audiences, unclear or risky licensing claims, sensitive wording, or two materially different user journeys with no clear primary path. + +When you do ask, ask one focused question, explain what actually differs between the options, recommend one, and say why in a sentence. + +If you cannot ask, pick the safest option and state the assumption in your summary to the user, not in the README. + +## Scope + +Change the README. Change other documentation only when the user asked for it. + +Do not touch application behavior, architecture, source, dependencies, generated files, snapshots, fixtures, test expectations, or third party content. Do not rewrite unrelated prose elsewhere in the repository because you noticed it could be better. + +If writing the README exposes a bug or a contradiction between docs and code, report it to the user. Do not silently fix it in the implementation. + +## Gotchas + +- Treating the section list as a checklist instead of running the inclusion tests in `references/section-rules.md`. +- Adding an emoji to `## Features`. It never takes one. `## Background` and `## Why?` never take one either. +- Forgetting emojis on the individual feature bullets. The heading has none, so every bullet has one. +- Writing `## Why?` and `## Background` with overlapping content. Pick the one that does the job. +- Adding `Prerequisites` when the only prerequisite is the language runtime the install command already implies. +- Adding `Examples` when the repository has no examples, or pointing it at test fixtures that were never meant as examples. +- Writing `Next Steps` that only relink earlier sections. It must be a progression toward something new. +- Reaching for an alert to break up the page rather than because the content is crucial for the reader's success. GitHub recommends one or two per document, never consecutive, and more are justified only when every alert independently earns its place. +- Choosing alert severity by how important the sentence feels. `WARNING` and `CAUTION` mean something specific. Check the definitions. +- Inferring features from filenames. A directory named `cache/` is not evidence of a caching feature. +- Documenting `npm run build` without opening the manifest to see whether that script exists. +- Assuming MIT instead of reading the LICENSE file, or implying an unlicensed project is open source. +- Adding a banner the repository does not carry, a badge block to a repository that is not a published package, or a Documentation bullet pointing nowhere. Chrome is found, never fabricated. A LICENSE file alone earns no badge. +- Copying the current Nuxt README's structure. Take its principles, not its outline. +- Making the README longer to make it look complete. A shorter README that answers the same questions is the better one. +- Expanding into a repository-wide cleanup. The README is the deliverable. diff --git a/skills/nuxt-style-readme/assets/readme-template.md b/skills/nuxt-style-readme/assets/readme-template.md new file mode 100644 index 0000000000..7d73c8467f --- /dev/null +++ b/skills/nuxt-style-readme/assets/readme-template.md @@ -0,0 +1,203 @@ +# README template + +A skeleton of optional parts, not a form to fill in. Read it when building a README from nothing or substantially restructuring one. Skip it for targeted edits. + +How to use it: + +1. Delete every section the repository does not earn. Check each one against `references/section-rules.md`. +2. Keep the order of what remains. +3. Replace every `` with something you read in the repository. If you cannot, delete the line. A placeholder filled with a plausible guess is worse than a missing section. +4. Delete every `` comment. They are instructions to you, not content. The one exception is the `` marker at the bottom, which is content and stays whenever badges are used. +5. Rename and re-emoji headings to fit the project. `โš™๏ธ Configuration` may be `โš™๏ธ Settings`. `๐ŸŽจ Icons` may be anything the project is actually about. + +--- + + + +[![ banner]()]() + +[![npm version][npm-version-src]][npm-href] +[![npm downloads][npm-downloads-src]][npm-href] +[![License][license-src]][license-href] + +# + +<!-- Package name for a publishable package, product name otherwise. --> + +<One sentence saying what this is and who it is for.> + +<!-- Only when the targets exist. Delete otherwise. --> + +- [๐Ÿ“–  Documentation](<docs site url>) +- [๐Ÿ‘พ  Playground](<path or url>) + +<!-- At most one alert, only for a legal, safety, or scope caveat. Delete otherwise. + For private or license-constrained projects the alert can replace the sentence above. --> + +> [!IMPORTANT] +> <Constraint that changes how someone may use this project.> + +## Why? + +<!-- Only when a reader would still ask why this exists. One or two short paragraphs. + Do not use both Why? and Background unless they say genuinely different things. --> + +## Features + +<!-- No emoji on this heading. One emoji on every bullet. About four to fifteen + bullets, more only when genuinely earned. --> + +- <emoji> **<Capability>:** <One short present-tense sentence stating what it does for the reader.> +- <emoji> **<Capability>:** <One short present-tense sentence stating what it does for the reader.> +- <emoji> **<Capability>:** <One short present-tense sentence stating what it does for the reader.> + +## Background + +<!-- Only when context is needed before the implementation makes sense. --> + +## ๐Ÿ“‹ Prerequisites + +<!-- Only for things the install step does not provide: accounts, credentials, + licenses, services, platforms, hardware. Not the language runtime. --> + +- <Requirement, with a link where one helps.> +- <Requirement.> +- Optional: <Requirement that only some users need.> + +## ๐Ÿš€ Quick Start + +<!-- Or "๐Ÿš€ Install" when installation is substantial enough to stand alone. + Never both when they would overlap. The primary command comes first. --> + +```<lang> +<the one command that gets someone from nothing to working> +``` + +<What happens next, and what the reader should see.> + +<!-- A numbered list works well when the tool then does several things on its own. --> + +## ๐Ÿ’ป Usage + +<!-- ๐Ÿ’ป for libraries, ๐Ÿงช for CLIs and applications. + Every example real, taken from the source or the manifest. --> + +<One or two sentences of framing.> + +```<lang> +<smallest complete example> +``` + +<Follow-up sentence, then further examples only if they show something new.> + +### <Sub-topic> + +<!-- Plain H3, no emoji. Use for a distinct aspect of normal use. --> + +## ๐Ÿ“ฆ Examples + +<!-- Only when runnable examples exist in the repository or are hosted somewhere. --> + +- [<Example name>](<path or url>): <what it demonstrates> +- [<Example name>](<path or url>): <what it demonstrates> + +## โš™๏ธ Configuration + +<!-- Only the options that matter. A table once there are more than about three. --> + +| Option | Default | Effect | +| ------- | ----------- | -------------- | +| `<key>` | `<default>` | <what changes> | + +## <emoji> <Domain section> + +<!-- The section named for what this project actually is. Usually one to three of them. + This is what stops the README reading like a template. --> + +## ๐Ÿ”ง How It Works + +<!-- "๐Ÿ—๏ธ Architecture" instead when the audience is contributors. + Only when understanding the internals changes how someone uses or extends it. --> + +<Conceptual explanation.> + +<!-- A linear pipeline can use a text diagram. Delete if the flow branches. --> + +```text +<Stage> โ”€โ”€โ”€โ”€โ”€โ”€โ”€ <what it does> + โ”‚ +<Stage> โ”€โ”€โ”€โ”€โ”€โ”€โ”€ <what it does> +``` + +## ๐Ÿ“ฆ Project Structure + +<!-- Only when the layout is non-obvious. Every line gets a comment. + ๐Ÿ—‚๏ธ instead when ๐Ÿ“ฆ is already taken by Examples or a packaging section. --> + +```text +<path> # <purpose> +<path> # <purpose> +``` + +## ๐Ÿฉน Troubleshooting + +<!-- Only for failure modes the repository actually shows evidence of. --> + +| Symptom | Fix | +| -------------------- | ------------------- | +| <what the user sees> | <what they do next> | + +## โš ๏ธ Limitations + +<!-- Only when there are real constraints. Stated plainly, not softened. --> + +- <Constraint, and what it means in practice.> + +## ๐Ÿ› ๏ธ Development + +<!-- Only when the repository is meant to be worked on. + Every command verified against the manifest scripts or CI. --> + +```<lang> +<command> # <what it does> +<command> # <what it does> +``` + +### How it fits together + +<!-- Optional. A few bullets mapping the main pieces to their responsibilities. --> + +### Releasing + +<!-- Optional. Only when there is a real release process. --> + +## โ›ฐ๏ธ Next Steps + +<!-- Only when there is a genuine progression, not a relink of earlier sections. + Ordered, most useful first, an emoji per item where one fits. --> + +1. <emoji> <Action, linked.> +2. <emoji> <Action, linked.> +3. ๐Ÿ› Hit a bug or have an idea? [Open an issue](<issues url>). + +## โš–๏ธ License + +<!-- Read the LICENSE file. Never infer. Delete this section if there is no license + and say nothing that implies the project is open source. --> + +Licensed under the [<license name>](./LICENSE) ยฉ <copyright holder>. + +<!-- When third party terms apply, add a second paragraph drawing the boundary + between the code license and those terms. --> + +<!-- Keep the marker line and definitions below only when badges are used above, + filled from references/style-guide.md for this package. Delete otherwise. --> + +<!-- Badges --> + +[npm-version-src]: <badge image url> +[npm-downloads-src]: <badge image url> +[npm-href]: <package registry url> +[license-src]: <badge image url> +[license-href]: ./LICENSE diff --git a/skills/nuxt-style-readme/references/section-rules.md b/skills/nuxt-style-readme/references/section-rules.md new file mode 100644 index 0000000000..d0a43815f6 --- /dev/null +++ b/skills/nuxt-style-readme/references/section-rules.md @@ -0,0 +1,169 @@ +# Section rules + +Which sections a README gets, in what order, and how each one is named. + +Read this before choosing an outline. Each section below has an inclusion test stated as something you can check in the repository. If the test does not pass, the section does not exist. + +Most READMEs land at six to nine H2 sections. A small script or single-purpose CLI can be complete at four. + +## Default order + +Skip any section the repository does not earn. Do not reorder without a reason. + +| Order | Section | Canonical heading | +| ----- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| 1 | Opening block: chrome and links when the repository provides them, title, description, at most one alert | `# Title` | +| 2 | Why? | `## Why?` | +| 3 | Features | `## Features` | +| 4 | Background | `## Background` | +| 5 | Prerequisites | `## ๐Ÿ“‹ Prerequisites` | +| 6 | Quick Start or Install | `## ๐Ÿš€ Quick Start` / `## ๐Ÿš€ Install` | +| 7 | Usage | `## ๐Ÿ’ป Usage` / `## ๐Ÿงช Usage` | +| 8 | Examples | `## ๐Ÿ“ฆ Examples` | +| 9 | Configuration | `## โš™๏ธ Configuration` / `## โš™๏ธ Settings` | +| 10 | Domain sections | project-specific, floats anywhere from Usage down, see below | +| 11 | How It Works or Architecture | `## ๐Ÿ”ง How It Works` / `## ๐Ÿ—๏ธ Architecture` | +| 12 | Project Structure | `## ๐Ÿ“ฆ Project Structure` | +| 13 | Troubleshooting | `## ๐Ÿฉน Troubleshooting` | +| 14 | Limitations | `## โš ๏ธ Limitations` | +| 15 | Development | `## ๐Ÿ› ๏ธ Development` | +| 16 | Next Steps | `## โ›ฐ๏ธ Next Steps` | +| 17 | License | `## โš–๏ธ License` | + +`Why?` sits before `Features` because it frames the problem the features answer. `Background` sits after, because it is context you need once you know what the thing is. The house repositories have no `Why?` yet, so its position is a chosen convention rather than observed evidence. + +No emoji may appear on two H2 headings in the same README. If `Examples` and `Project Structure` both exist, `Examples` keeps `๐Ÿ“ฆ` and `Project Structure` takes `๐Ÿ—‚๏ธ`. + +## Features + +**Include when** the project exposes capabilities a user can name. That covers almost every tool, library, package, application, CLI, and script. + +**Omit when** the project exposes a single capability, where the one-sentence description already is the feature list. Two or more nameable capabilities earn the section even when the description mentions them all. + +## Why? + +**Include when** a reader who understands what the project is would still ask why it exists. Useful when the project competes with an obvious alternative, or solves a problem whose difficulty is not visible. + +**Omit when** the answer is already obvious from the description, or when it would restate the feature list in paragraph form. + +## Background + +**Include when** the reader needs historical, ecosystem, or problem context before the implementation makes sense. Typical for projects built on an undocumented API, a format quirk, or a constraint imposed from outside. + +**Omit when** `Why?` already carries the context. These two overlap heavily. Use both only when one explains motivation and the other explains circumstances, and neither can absorb the other. + +## Prerequisites + +**Include when** the user must have something in place before the install command will work: an account, a credential, a license key, a service, a permission, specific hardware, a supported platform, or a runtime the install step does not provide. + +**Omit when** the only requirement is the language runtime that the install command already implies. `npm install` does not need a bullet telling the reader to install Node.js. When that is the only requirement, do not restate the runtime as prose elsewhere either, since a version floor from `engines` is documentation the manifest already carries. + +Keep it to a short bullet list. Mark genuinely optional items as optional. + +## Quick Start and Install + +**Include one of them always.** A README without a path to running the thing has failed. + +Default to `Quick Start`, and put the primary command in the first code block. Reach for `Install` only when installation is substantial enough that mixing it with first use would obscure both. + +**Never create both** when they would share most of their content. Pick the one that fits and let it carry the whole path. + +Optimize for time to first success. Explanation goes after the command, not before it. + +## Usage + +**Include when** the reader needs more than the first command to operate the project normally. + +**Omit when** Quick Start already showed the entire surface area. + +Use `## ๐Ÿ’ป Usage` for libraries and packages, where usage means code the reader writes. Use `## ๐Ÿงช Usage` for CLIs, applications, scripts, and userscripts, where usage means commands or actions the reader performs. + +Every example must be real. Take imports, exports, flags, and signatures from the source or the manifest. + +## Examples + +**Include when** the repository contains examples a user can actually open: an `examples/` directory, a playground, a demo application, a hosted sandbox, or a runnable sample. + +**Omit when** there are none. Test fixtures are not examples. A section that links to nothing is worse than no section. + +Link directly to each example and say in a few words what it demonstrates. Format each entry as `- [Example name](./path): what it demonstrates`. + +## Configuration + +**Include when** the user can meaningfully change how the project behaves through options, environment variables, a config file, or settings. + +**Omit when** configuration is internal, or when a single option is better explained inline where it is used. + +Document the options that matter. Do not transcribe an entire schema. A table of key, default, and effect scans better than prose once there are more than about three options. + +## Domain sections + +The strongest READMEs in this style carry one to three sections named for what the project actually does: `## ๐Ÿ” Managing Secrets`, `## ๐ŸŽจ Icons`, `## ๐Ÿ“ฆ ZIP Structure`, `## ๐Ÿ” License key`. + +**Include when** a meaningful part of the project does not fit any generic heading. Name the section after the thing, pick an emoji that fits its meaning, and place it where a reader would need it. + +A domain section never absorbs content that passes a generic inclusion test. Context that fits `Background` goes to `Background`, and a domain section carries what no generic heading fits. + +This is what keeps the style from reading as a template. + +## How It Works and Architecture + +**Include when** understanding the internal flow changes how someone uses or contributes to the project. + +Use `How It Works` for a conceptual explanation aimed at users. Use `Architecture` for structural documentation aimed at contributors. + +**Omit when** the internals are ordinary. Do not expose implementation detail because it exists. + +## Project Structure + +**Include when** the repository has a layout a contributor could not infer, and the tree explains something. + +**Omit when** the folders are self-explanatory. `src/`, `tests/`, and `docs/` need no annotation. + +Annotate every line with what it is for. An unannotated tree is decoration. + +## Troubleshooting + +**Include when** the repository shows evidence of real failure modes: known issues, error handling with specific messages, compatibility caveats, retry logic, or existing troubleshooting notes. + +**Omit when** you would be inventing problems. Never speculate about failures. + +Use a table of symptom and fix. The symptom is what the user sees, the fix is what they do next. + +## Limitations + +**Include when** the project has constraints someone should understand before depending on it: unsupported cases, formats that may change, scope boundaries, or known incompleteness. + +**Omit when** there is nothing honest to say. + +State them plainly. A limitation written as a feature is a lie with extra steps. A workaround does not demote a constraint: state the constraint here and let `Troubleshooting` carry the recovery step. + +## Development + +**Include when** the repository is meant to be worked on and has commands worth listing: a test suite, a build, linting, a release process. + +**Omit when** the project is a single file with no tooling. + +Every command must exist in the manifest scripts, the CI workflow, or tooling the repository declares, such as a Makefile target or a tool configured in the manifest. Contributor-facing detail belongs here and below, not mixed into the user-facing sections above. + +Plain H3 subsections work well here: how the pieces fit together, how to add a thing, how to release. + +A repository with a `CONTRIBUTING.md` gets a link from this section, not a standalone Contributing section. A standalone section is earned only by real content that no `CONTRIBUTING.md` carries. Support and acknowledgment material folds into `Next Steps` or the introduction rather than taking its own heading. + +## Next Steps + +**Include when** there is a real progression after setup: something to read, something to try, something to extend. + +**Omit when** the entries would only relink sections the reader just passed. + +Use an ordered list, most useful action first, usually with one fitting emoji per item. Ending with an invitation to open an issue is a good close. + +## License + +**Include when** the repository has a LICENSE file, a `license` field in its manifest, or licensing that materially affects use. + +Use the actual license. Read the LICENSE file. A manifest that declares a license without shipping a LICENSE file still licenses the project, so name that license, link nothing, and leave the copyright holder out, because no file names one. `UNLICENSED` in a manifest means the opposite: the project is not licensed for reuse. Never infer a license from anything else. + +When third party assets, data, APIs, or paid content carry different terms than the code, say so in a separate sentence or paragraph and make the boundary explicit. + +If there is no license, do not imply the project is open source. Saying the project is unlicensed is more useful than saying nothing. diff --git a/skills/nuxt-style-readme/references/style-guide.md b/skills/nuxt-style-readme/references/style-guide.md new file mode 100644 index 0000000000..329fba8876 --- /dev/null +++ b/skills/nuxt-style-readme/references/style-guide.md @@ -0,0 +1,224 @@ +# Style guide + +How the README reads and renders. Read this before writing prose. + +Conventions are split by how much they bend. Strong defaults hold unless the repository gives you a reason. Conditional patterns depend on a condition you can check. Repository-specific decisions are yours to make from evidence. The last group never applies. In order: voice, prose, headings, code blocks, links, and license wording, then opening chrome, emoji, tables, diagrams, and alerts, then the repository-specific list, then the avoid list. + +## Strong defaults + +### Voice + +Write for a competent developer who has never seen this project. Explain what they cannot infer and skip what they can. + +Second person for instructions. Present tense for behavior: "The build refuses to write the file if a check fails", not "will refuse". State facts directly and let them carry their own weight. If something is genuinely good, the specific detail proves it better than the adjective. + +### Prose + +- One idea per paragraph. Two to four sentences is the working range. A single strong sentence is often enough. +- Prefer a concrete noun to an abstraction. "Keychain entry" beats "credential storage mechanism". +- Cut phrases that add no information: "simply", "just", "of course", "as you can see", "it is worth noting that". +- Cut sentences that restate the heading. +- The dash and semicolon rules are fixed in `SKILL.md` and are not repeated here. +- Write in the language of the repository's existing documentation. For English, use American spelling unless the existing README is consistently spelled otherwise. + +### Headings + +Title case for H2 section names: `Quick Start`, `How It Works`, `Next Steps`, `Project Structure`. + +H2 sections take one leading emoji and a space. `Features`, `Why?`, and `Background` are the exceptions, as fixed in `SKILL.md`. + +H3 and below stay plain. `### Theming`, `### Naming`, `### How it fits together`, `### Releasing`. No emoji, and sentence case is fine at this level. + +Pick a heading pattern once and hold it for the whole document. + +### Code blocks + +Always tag the language. Use `text` for output, trees, and diagrams that are not code. + +Show the command a reader would actually type. When a block lists several commands, align trailing comments into a column: + +````markdown +```bash +bun install # install dependencies and set up git hooks +bun run lint # type-checked ESLint +bun test # run the test suite +bun run build # bundle src/ into dist/ +``` +```` + +Introduce every code block with one short lead-in sentence, ending in a period, or in a colon when the block completes the sentence. Longer explanation goes after the block, so a reader scanning for the install line hits it immediately. + +### Links + +Relative links for anything inside the repository, in `./path` form. GitHub resolves these against the current branch, and they survive a clone. Paths resolve from the directory holding the README, not the repository root. A README in `packages/core/` links its own source as `./src/index.ts` and the repository license as `../../LICENSE`. + +```markdown +[`scripts/build.ts`](./scripts/build.ts) +``` + +External links point at the most specific page that answers the reader's question, not the product homepage. Link the first meaningful mention of an external tool, format, or standard, then use the bare name afterward. A linked feature label counts as that first mention, so the bullet's own sentence and later prose use the bare name. Do not link the same target repeatedly. A Next Steps entry may point at a target that was already linked earlier, because every entry in that list is a link by design. + +Never link a file that does not exist. + +### License wording + +One line when the license is simple and the repository owns everything in it: + +```markdown +Licensed under the [MIT license](./LICENSE) ยฉ Jonathan Russ. +``` + +Two parts when third party terms apply. State the code license first, then draw the boundary explicitly: + +```markdown +The tooling and wrapper code in this repository is [MIT licensed](./LICENSE). + +That license covers the code only. It grants no rights to <asset>, which is +<terms> and governed by the [<name> license](url). +``` + +Name the copyright holder from the LICENSE file, never from a guess. + +## Conditional patterns + +### Opening chrome + +A banner, badges, and Documentation or Playground bullets open the README only when the repository provides them. The inclusion tests are fixed in `SKILL.md`. The format, adapted from the Nuxt module family: + +```markdown +[![<name> banner](./.github/assets/banner.png)](<docs site url>) + +[![npm version][npm-version-src]][npm-href] +[![npm downloads][npm-downloads-src]][npm-href] +[![License][license-src]][license-href] + +# <Title> + +<One sentence.> + +- [๐Ÿ“–  Documentation](<docs site url>) +- [๐Ÿ‘พ  Playground](./playground) +``` + +Badge images use the reference style, one badge per source line, with the definitions collected at the bottom of the file under a `<!-- Badges -->` comment: + +```markdown +<!-- Badges --> + +[npm-version-src]: https://img.shields.io/npm/v/<package>/latest.svg?style=flat&colorA=18181B&colorB=28CF8D +[npm-downloads-src]: https://img.shields.io/npm/dm/<package>.svg?style=flat&colorA=18181B&colorB=28CF8D +[npm-href]: https://npmjs.com/package/<package> +[license-src]: https://img.shields.io/npm/l/<package>.svg?style=flat&colorA=18181B&colorB=28CF8D +[license-href]: ./LICENSE +``` + +The banner links to the documentation site when one exists, otherwise it stands plain. The badge set is npm version, npm downloads, and license, with the license badge only when a LICENSE file exists. The same three-badge set maps to other registries through the matching shields endpoints, `pypi/v`, `pypi/dm`, and `pypi/l` for a Python package and `crates/v`, `crates/d`, and `crates/l` for a Rust crate, with the same style parameters. An ecosystem badge, such as the Nuxt badge on a Nuxt module, is a repository-specific decision. `colorB` may take the project's accent color. Each bullet's link text is the emoji, a space, a ` ` entity, then the label, exactly as shown. + +### Emoji for H2 headings + +Pick for meaning, not decoration. Most rows come from the house repositories, the rest extend the same logic to sections those repositories have not needed yet, and reusing them keeps repositories recognizable as one family: + +| Emoji | Section | +| ----- | -------------------------------------------------------- | +| ๐Ÿ“‹ | Prerequisites | +| ๐Ÿš€ | Quick Start, Install | +| ๐Ÿ’ป | Usage, for libraries and packages | +| ๐Ÿงช | Usage, for CLIs, applications, and scripts | +| ๐Ÿ“ฆ | Examples, Project Structure, packaging, archive contents | +| โš™๏ธ | Configuration, Settings | +| ๐Ÿ”ง | How It Works | +| ๐Ÿ—๏ธ | Architecture | +| ๐Ÿ—‚๏ธ | Project Structure, when ๐Ÿ“ฆ is already taken | +| ๐Ÿ” | Secrets, credentials, license keys, security | +| ๐Ÿ”‘ | Keys and tokens, when ๐Ÿ” is already taken | +| ๐ŸŽจ | Icons, themes, visual assets | +| ๐Ÿฉน | Troubleshooting | +| โš ๏ธ | Limitations | +| ๐Ÿ› ๏ธ | Development | +| โ›ฐ๏ธ | Next Steps | +| โš–๏ธ | License | + +For a section not on this list, choose an emoji a reader recognizes instantly and can connect to the heading without thinking. Avoid anything abstract, ornamental, or clever. + +One emoji per H2. Uniqueness is counted within a list, not across the document: no emoji appears twice among the H2 headings, and none appears twice among the feature bullets. A bullet may carry the same emoji as an H2. + +### Tables + +Use a table when a reader will scan rather than read, and when every row has the same shape. Three or more parallel items is the usual threshold. + +Good uses: option and default and effect, symptom and fix, alias and command, package and prefix, stage and responsibility, folder and purpose. + +Keep cells short. A cell running past roughly one line means the content wanted prose or its own subsection. Center a column only when its values are short markers. + +### Flow diagrams + +When a project is a pipeline and the stage names carry the explanation, a plain diagram beats a paragraph: + +````markdown +```text +Interceptor โ”€โ”€โ”€โ”€โ”€โ”€โ”€ captures the composition response + โ”‚ +Extractor โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ enumerates referenced assets + โ”‚ +Downloader โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ fetches them in parallel + โ”‚ +Composer โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ assembles combined.glb +``` +```` + +Every stage gets a short description on its own line. Use this only when the flow is genuinely linear. It does not survive branching. + +Annotated file trees follow the same rule. Every line earns a comment or the tree is decoration. + +### GitHub alerts + +The five supported types, with GitHub's own definitions: + +| Type | GitHub's definition | +| ----------- | ------------------------------------------------------------------------ | +| `NOTE` | "Useful information that users should know, even when skimming content." | +| `TIP` | "Helpful advice for doing things better or more easily." | +| `IMPORTANT` | "Key information users need to know to achieve their goal." | +| `WARNING` | "Urgent info that needs immediate user attention to avoid problems." | +| `CAUTION` | "Advises about risks or negative outcomes of certain actions." | + +Syntax is a blockquote whose first line is the bracketed type in capitals: + +```markdown +> [!IMPORTANT] +> Key information users need to know to achieve their goal. +``` + +GitHub's stated limits, quoted: "Use alerts only when they are crucial for user success and limit them to one or two per article to prevent overloading the reader. Additionally, you should avoid placing alerts consecutively." Also: "Alerts cannot be nested within other elements." + +Default to one or two per README. More are justified only when every alert independently passes the crucial-for-success test and no two sit adjacent. The longest README in this family carries four. + +Choose the type by consequence, not by emphasis. A legal or licensing constraint is `IMPORTANT`. An action that can destroy data or expose a secret is `CAUTION`. Something that breaks the install for everyone is `WARNING`. A convenience is `TIP`. Context is `NOTE`. + +If the point needs several paragraphs or a list, it needs a section, not an alert. + +These rules were recorded from GitHub's documentation when this skill was written. Confirm them against the live page before relying on them, and say so if you could not. + +## Repository-specific decisions + +Decide these from the repository, not from a rule: + +- Whether the title is the package name or a product name. Publishable packages use the exact package name so a reader can match it against what they install. +- Which section carries the domain. Every repository has one or two areas that do not fit a generic heading, and naming them well is what makes the README feel written rather than generated. +- Where the depth goes. Some projects need a long configuration table and a two-line usage section. Others are the reverse. +- Whether a diagram, a table, or a paragraph explains a thing best. +- How much a contributor needs. A library with a release process needs more than a userscript. +- Which emoji fits a section this list does not cover. + +## Avoid + +A final sweep before you finish. The chrome inclusion tests live in `SKILL.md`, and the formats are under Opening chrome above. + +- A table of contents. GitHub generates an outline from the headings. +- HTML anchor tags around headings. GitHub already generates anchors. +- "Powerful", "modern", "blazing fast", "seamless", "robust", "smart", "advanced", "flexible", "optimized", "easy to use", "out of the box", and "leverage" as a verb, unless the surrounding sentence makes the concrete meaning explicit. +- Sections whose only content is a link to another section. +- Explaining what a reader of this project already knows. A Rust crate's README does not explain what Cargo is. +- Filler transitions: "In this section we will", "Let's dive in", "Now that we have covered". +- Long unbroken prose where a table or list would be scanned instead of read. +- Making it longer to make it look finished.