agentleFS
lingengyuanlingengyuan/my-skills/.claude/skills/readme-maintainer/SKILL.md

readme-maintainer

Skill9 starsChanged 3 days agoMITView on GitHub

Maintain, update, and rewrite concise, publication-ready repository README files grounded in codebase facts. Use when updating README.md, refreshing installation and usage guides, verifying CLI commands, or aligning bilingual documentation.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 11 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Verify claims against code: Verify installation steps, prerequisites, environment variables, and CLI commands against actual repository …

    line 17
  2. Distinctive:

    Delete meta-discourse, author reflections, and review commentary.

    line 25
  3. Distinctive:

    Keep only sections the reader needs.

    line 28
  4. Distinctive:

    If bilingual READMEs exist, ensure semantic parity across sections.

    line 31
  5. Distinctive:

    Verify & report: Test links, verify command syntax, and report material changes outside the README.

    line 36
  6. Distinctive:

    Grounding: Never invent compatibility guarantees, benchmarks, test coverage stats, or feature lists.

    line 40
  7. Distinctive:

    Brevity with completeness: Delete conversational filler, but keep essential setup commands, parameter definitions, and failure recovery …

    line 42
  8. Distinctive:

    Before completing the task, verify:

    line 46
  9. Distinctive:

    All installation and run commands match repository build tools.

    line 48
  10. Distinctive:

    All internal links and relative file paths resolve correctly.

    line 50
  11. Distinctive:

    If bilingual, both language sections cover identical concepts without drift.

    line 51

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

README Maintainer Skill

Generate and maintain clear, verified README files directly from repository source code, build manifests, and runtime configuration. Standard Markdown is assumed knowledge.

Workflow

  1. Locate README and files: Identify repository root and existing README.md. Read the current content.
  2. Collect repository facts: Inspect package.json, Cargo.toml, pyproject.toml, CLI help outputs, and configuration files. For repository-wide updates, run:
    bash "<skill-dir>/scripts/collect_repo_facts.sh" "<repo-path>"
  3. Verify claims against code: Verify installation steps, prerequisites, environment variables, and CLI commands against actual repository source code. Delete stale claims and unverified statements.
  4. Structure the document:
    • Project Overview: One concise sentence describing what the project does.
    • Prerequisites & Installation: Exact runtime versions, package managers, and setup commands.
    • Quick Start / Basic Usage: Minimal runnable command or code example with realistic input and output.
    • Configuration / Key Options: Essential configuration table or common operations.
    • Documentation Links: Link detailed architectural guides, API references, and development procedures to existing files instead of duplicating them.
  5. Apply publication pass:
    • Delete meta-discourse, author reflections, and review commentary.
    • State product features and constraints directly in active voice.
    • Define each technical fact in one authoritative place.
    • Keep only sections the reader needs. A README is an entry point, not an exhaustive encyclopedia.
  6. Align bilingual documentation (if applicable):
    • Match the existing language convention.
    • If bilingual READMEs exist, ensure semantic parity across sections. Run:
      bash "<skill-dir>/scripts/check_bilingual_readme.sh" README.md
      The script accepts one file with ## English / ## 简体中文 sections, or README.md plus a companion README.<lang>.md; either file works as the argument. It compares heading counts, so keep the section structure identical across languages. A single-language README exits 0.
  7. Verify & report: Test links, verify command syntax, and report material changes outside the README.

Guidelines

  • Grounding: Never invent compatibility guarantees, benchmarks, test coverage stats, or feature lists.
  • Single source of truth: Link to specialized documentation (architecture, full API, contributing guides) rather than duplicating large sections.
  • Brevity with completeness: Delete conversational filler, but keep essential setup commands, parameter definitions, and failure recovery notes.

Verification Checklist

Before completing the task, verify:

  1. All installation and run commands match repository build tools.
  2. Code examples and CLI flags reflect current implementations.
  3. All internal links and relative file paths resolve correctly.
  4. If bilingual, both language sections cover identical concepts without drift.
  5. Output contains no internal editing chatter or temporary task notes.

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.