agentleFS
therain2020therain2020/therain2020-agent/.claude/skills/update-docs/SKILL.md

update-docs

Skill0 starsChanged 6 months agoMITView on GitHub

Update all project documentation, repository metadata, and progress tracking when the codebase has significantly changed. Handles README (EN/CN), CLAUDE.md, CHANGELOG, pyproject.toml, GitHub About/description/topics, and release notes. CRITICAL: bilingual docs are written independently, NOT translated.

90 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use get-pr-reviews, push-everything 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.
  • saffron-healthSkill

    get-pr-reviews

    Get nicely formatted output of the last review comments on a PR. Used internally by other skills.

    Also in 3 projects that use this

  • saffron-healthSkill

    push-everything

    Stage ALL changes in the repository (not just session changes), commit, and push. Use when you need to commit all pending changes.

    Also in 3 projects that use this

  • TheKREATORSSkill

    instinct-export

    Export instincts from project/global scope to a file

    Also in 3 projects that use this

  • TheKREATORSSkill

    instinct-import

    Import instincts from file or URL into project/global scope

    Also in 3 projects that use this

  • NVIDIASkill

    generate-spec

    Produce a feature specification covering API changes, backward compatibility, cross-language impact, performance, and a file-level change plan. Use when designing a new feature, planning a significant change, or the user asks to spec something out.

    Also in 3 projects that use this

  • belokonmSkill

    fullstack-developer

    End-to-end feature expert specializing in frontend-backend integration, system architecture, and complete application development

    Also in 4 projects that use this

  • +1 more from saffron-health
  • +1 more from TheKREATORS
  • Other versions90 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 90

    1. vercel/next.js★ 144ksame name
    2. pipecat-ai/pipecat★ 17ksame name
    3. anyproto/anytype-ts★ 9.1ksame name
    4. vladmandic/sdnext★ 7.4ksame name
    5. ArcReel/ArcReel★ 6.6ksame name
    6. dotnet/sdk★ 3.2ksame name
    7. huggingface/OpenEnv★ 2.9ksame name
    8. meta-pytorch/OpenEnv★ 2.8ksame name
    9. man-group/ArcticDB★ 2.6ksame name
    10. fabro-sh/fabro★ 1.8ksame name

    80 more not listed

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

Show its rules and text

We split this skill into the rules it gives an agent

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

  • 0

    Common

    Most of the 84 edited versions we read keep these.

  • 11

    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:

    When triggered, follow this workflow.

    line 26
  2. Distinctive:

    Read the current state of all docs that may need updating:

    line 30
  3. Very specific:

    Check current test count: pytest tests/ -q

    line 36
  4. Very specific:

    Check current GitHub repo state: gh repo view --json description,homepageUrl,topics

    line 37
  5. Distinctive:

    Avoid: 进行/予以/有着/具有 — just say the verb directly

    line 80
  6. Distinctive:

    Update GitHub repo with:

    line 98
  7. Distinctive:

    Read both READMEs aloud in your head — does each sound natural in its language?

    line 109
  8. Distinctive:

    Don't just copy English README into Chinese and tweak wording — rewrite from scratch

    line 120
  9. Distinctive:

    Don't use 进行 + verb (e.g., 进行操作 → just use the verb)

    line 121
  10. Distinctive:

    Don't leave stale test counts in badges or body text

    line 122
  11. Distinctive:

    Don't forget GitHub About — it's separate from README

    line 123
  12. Distinctive:

    Don't forget to update CLAUDE.md architecture table when modules are added/removed

    line 124
  13. Distinctive:

    Don't use machine-translation filler words like 此外、与此同时、值得注意的是

    line 125

“Common” is measured: kept by at least 6 in 10 of the 84 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

Update Project Documentation Skill

When triggered, follow this workflow. Never skip steps.

Phase 1: Assess Current State

  1. Read the current state of all docs that may need updating:
    • README.md — English readme
    • README.zh-CN.md — Chinese readme
    • CLAUDE.md — project instructions for Claude
    • CHANGELOG.md — release history
    • pyproject.toml — version + description
  2. Check current test count: pytest tests/ -q
  3. Check current GitHub repo state: gh repo view --json description,homepageUrl,topics
  4. Review recent commits since last release to understand what changed.

Phase 2: Plan Content (Critical Step)

Before writing a single word, list what needs to change in each doc:

DocWhat changedAction
README.md...add / rewrite / remove
README.zh-CN.md...add / rewrite / remove
CLAUDE.md...update table / test count
CHANGELOG.md...add new version entry
pyproject.toml...bump version / update description
GitHub About...update description + topics

Phase 3: Write (Bilingual Rule — Most Important)

The Golden Rule

English and Chinese READMEs are written INDEPENDENTLY. Never translate.

Translation produces unnatural Chinese that reads like machine output. Signs of bad translation:

  • English word order forced into Chinese sentences
  • Overly long sentences with too many clauses
  • Stiff academic vocabulary where colloquial would be natural
  • Directly translated metaphors that don't work in Chinese

How to write each version

English (README.md):

  • Direct, developer-oriented
  • Explain the "why" explicitly
  • Use concrete examples
  • Active voice, present tense
  • Short paragraphs, clear headings

Chinese (README.zh-CN.md):

  • Natural Chinese engineering prose — write like a Chinese developer would
  • Shorter sentences. Chinese reads faster. Be concise.
  • The "why" is often implied through contrast, not spelled out
  • Technical terms: use standard Chinese translations where they exist (不要中英混杂), but keep code identifiers in English
  • Bullet points should be terse — one clause each
  • Avoid: 进行/予以/有着/具有 — just say the verb directly

Content parity, not translation parity

Both READMEs should cover the same topics, but the structure, emphasis, and phrasing differ:

  • English might spend 3 sentences explaining a concept; Chinese might nail it in 8 characters
  • Chinese might use a concrete analogy that resonates with Chinese developers; English might use a different one
  • The order of sections may differ if one language flows better that way

Phase 4: Update All Artifacts

  1. README.md — write naturally in English
  2. README.zh-CN.md — write naturally in Chinese, independently
  3. CLAUDE.md — update architecture table, test count, any stale references
  4. CHANGELOG.md — add new version entry with bullet-point summary
  5. pyproject.toml — bump version if releasing, update description
  6. GitHub repo — update About description, homepage URL, topics

Update GitHub repo with:

gh repo edit --description "..." --homepage "..."
gh repo edit --add-topic "..."  # repeat for each topic

Phase 5: Verify

  1. ruff check . --fix --unsafe-fixes — lint clean
  2. pytest tests/ -q — all tests pass
  3. git diff --stat — review what changed
  4. Read both READMEs aloud in your head — does each sound natural in its language?

Release Flow (if version bump needed)

python scripts/bump_version.py patch|minor|major
# Then follow standard-dev-workflow for the release PR.

Common Mistakes to Avoid

  • Don't just copy English README into Chinese and tweak wording — rewrite from scratch
  • Don't use 进行 + verb (e.g., 进行操作 → just use the verb)
  • Don't leave stale test counts in badges or body text
  • Don't forget GitHub About — it's separate from README
  • Don't forget to update CLAUDE.md architecture table when modules are added/removed
  • Don't use machine-translation filler words like 此外、与此同时、值得注意的是

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.