agentleFS
sinediedsinedied/agent-skills/.agents/skills/readme/SKILL.md

readme

Skill4 starsChanged 5 months agoMITView on GitHub

Create or update a root README.md file for any project repository. Use when a user asks to create a README, generate a README for a project, write project documentation, update an existing README, or improve a README. Also use when setting up a new project and the user wants a polished README file.

39 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use favicon, glossary and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • cpiprintSkill

    favicon

    Generate favicons from a source image

    Also in 3 projects that use this

  • Microsoft AzureSkill

    glossary

    Short glossary of domain terms used by the team.

    Also in 3 projects that use this

  • jaydubya818Skill

    how

    Use for runtime, ownership, layering, code-walkthrough, and placement questions.

    Also in 3 projects that use this

  • jaydubya818Skill

    why

    Use when design rationale must be recovered from source history and available records.

    Also in 3 projects that use this

  • 0xSeroSkill

    security

    Also in 3 projects that use this

  • Microsoft AzureSkill

    build

    Build the TypeSpec Rust emitter from source. Run this after cloning the repo, after pulling changes, or when TypeScript source files have been modified.

    Also in 3 projects that use this

  • +1 more from Azure

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 15 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 39 edited versions we read keep these.

  • 15

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create comprehensive, well-structured, and appealing README.md files for projects.

    line 9
  2. Distinctive:

    Use GFM (GitHub Flavored Markdown)

    line 62
  3. Distinctive:

    Use GitHub admonition syntax for callouts:

    line 63
  4. Very specific:

    Use <details> for collapsible sections when offering alternative setup methods

    line 80
  5. Very specific:

    Use centered <div align="center"> for the header block (logo, title, badges, nav links)

    line 81
  6. Distinctive:

    Use flat-square badge style consistently

    line 82
  7. Distinctive:

    Use bold text for feature names in feature lists

    line 83
  8. Distinctive:

    Do not overuse emojis (a few are fine, especially in feature lists)

    line 88
  9. Distinctive:

    Write in a clear, professional tone

    line 89
  10. Distinctive:

    Use code blocks with language identifiers for all code/command examples

    line 90
  11. Distinctive:

    Prefer actionable instructions ("Run this command") over passive descriptions

    line 91
  12. Distinctive:

    Do NOT include these sections — they have dedicated files:

    line 96
  13. Distinctive:

    After writing or updating the README:

    line 109
  14. Distinctive:

    Verify all links point to existing files/URLs

    line 111
  15. Distinctive:

    Ensure commands and code examples are accurate

    line 112
  16. Distinctive:

    Check that badge URLs are correct

    line 113
  17. Distinctive:

    If updating an existing README, ensure no important existing content was lost

    line 115

“Common” is measured: kept by at least 6 in 10 of the 39 edited versions of this file we could read. “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

README Creator

Create comprehensive, well-structured, and appealing README.md files for projects.

Workflow

  1. Analyze the project thoroughly
  2. Determine project type and appropriate README structure
  3. Generate or update the README.md
  4. Validate the result

Step 1: Analyze the Project

Examine the entire repository to understand its context. Look for:

  • Project identity: package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, etc.
  • Purpose: Existing README, docs folder, description fields, comments
  • Tech stack: Languages, frameworks, libraries, build tools
  • Project type: Application sample, CLI tool, library, monorepo, API, etc.
  • Entry points: How users install, configure, and run the project
  • Key features: What sets this project apart
  • Architecture: Directory structure, diagrams, component relationships
  • Development setup: Prerequisites, environment setup, dev containers, codespaces
  • Deployment: Cloud deployment, CI/CD, Docker, infrastructure-as-code
  • Assets: Logo, icons, screenshots, demo GIFs in docs/images or similar folders

Step 2: Determine Structure

Choose sections based on the project type. Not all sections apply to every project.

Common sections (most projects)

  • Title with logo/icon (if available)
  • Badges (build status, version, license, language)
  • Short description / tagline
  • Navigation links to major sections
  • Screenshot or demo GIF (if available)
  • Overview (for larger projects)
  • Features
  • Getting started / Installation
  • Usage / Running
  • Resources / Links (if relevant)
  • Troubleshooting / FAQ (if relevant)

Additional sections by project type

Application samples: Prerequisites, deployment instructions, architecture diagram, cost estimation CLI tools: Installation (npm/brew/etc.), command line options, examples Libraries: Installation, API reference or link to docs, examples Monorepos: Project structure table, links to sub-project READMEs

Step 3: Write the README

Formatting rules

  • Use GFM (GitHub Flavored Markdown)
  • Use GitHub admonition syntax for callouts:
    > [!NOTE]
    > Informational note.
    
    > [!TIP]
    > Helpful tip.
    
    > [!IMPORTANT]
    > Critical information.
    
    > [!WARNING]
    > Warning about potential issues.
    
    > [!CAUTION]
    > Dangerous action warning.
  • Use <details> for collapsible sections when offering alternative setup methods
  • Use centered <div align="center"> for the header block (logo, title, badges, nav links)
  • Use flat-square badge style consistently
  • Use bold text for feature names in feature lists

Style guidelines

  • Be concise and to the point — avoid filler text
  • Do not overuse emojis (a few are fine, especially in feature lists)
  • Write in a clear, professional tone
  • Use code blocks with language identifiers for all code/command examples
  • Prefer actionable instructions ("Run this command") over passive descriptions
  • Include a star call-to-action if appropriate ("⭐ If you like this project, star it on GitHub")

Sections to exclude

Do NOT include these sections — they have dedicated files:

  • LICENSE
  • CONTRIBUTING
  • CHANGELOG
  • CODE_OF_CONDUCT
  • SECURITY

Reference examples

See references/examples.md for structural patterns extracted from high-quality READMEs.

Step 4: Validate

After writing or updating the README:

  • Verify all links point to existing files/URLs
  • Ensure commands and code examples are accurate
  • Check that badge URLs are correct
  • Confirm the structure matches the project type
  • If updating an existing README, ensure no important existing content was lost

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.