agentleFS
Sign inStart free
Smaui94Smaui94/ClaudeSkillCollection/markdown-readme-google-style/SKILL.md

markdown-readme-google-style

Skill0 starsChanged 9 days agoMITView on GitHub

Apply the Google README guidelines (https://google.github.io/styleguide/docguide/READMEs.html) when writing, editing, or reviewing README.md files and the Markdown documentation of a project. Use for any README work, when creating a new package/directory, and when asked to check READMEs against Google style.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Make sure README.md of a directory renders when that directory is viewed on the hosting site (e.g.

    line 14
  2. Very specific:

    Keep README.md on the default branch (HEAD) so the repository index shows it.

    line 15
  3. Distinctive:

    Put a README.md in the top-level directory of the product or library codebase.

    line 18
  4. Distinctive:

    Do not put it inside the product's documentation directory.

    line 19
  5. Distinctive:

    Keep READMEs current first for directories that expose interfaces to other teams or users.

    line 21
  6. Distinctive:

    Every package-level README.md includes or links to:

    line 25

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Google README guidelines

Source: https://google.github.io/styleguide/docguide/READMEs.html

Follow the rules below when writing or changing README files. When reviewing, report violations as path - rule - fix. If a project already has stricter or different documentation conventions, match them unless the user asks otherwise. The source covers READMEs only; for general Markdown formatting see https://google.github.io/styleguide/docguide/style.html.

File

  • Name the file exactly README.md: the .md extension is required and the name is case-sensitive.
  • Make sure README.md of a directory renders when that directory is viewed on the hosting site (e.g. GitHub, Codeberg).
  • Keep README.md on the default branch (HEAD) so the repository index shows it.

Where

  • Put a README.md in the top-level directory of the product or library codebase.
  • Do not put it inside the product's documentation directory.
  • Give every top-level directory of a code package an up-to-date README.md.
  • Keep READMEs current first for directories that expose interfaces to other teams or users.

What

  • Include at least a link to user- and/or team-facing documentation.
  • Every package-level README.md includes or links to:
    1. What the package or library contains and what it is used for.
    2. Points of contact (name, issue tracker, or team channel; do not publish private e-mail addresses without the owner's consent).
    3. Status, e.g. deprecated or not for general release.
    4. How to use it, with sample code, copyable build/test commands, or similar.
    5. Links to relevant documentation.
  • Directory-level READMEs stay short: what is in the directory, how it is used, and links to the details instead of repeating them.

Review checklist

  • Does every top-level directory of the code package have a README.md?
  • Does each README answer items 1 to 5 above or link to where they are answered?
  • Are all links and commands valid and current (paths exist, commands run)?
  • Does the README list the directory contents as they actually are?

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free