# Readme Maintainer

> Update or rewrite project README files directly with the current session model (Codex/Claude Code) using local repository facts, without calling external README generation APIs. Use when users ask to "update README", "rewrite readme.md", "generate project documentation", "refresh usage/install sections", or "align README with latest code changes" for a local repo. Use when this capability is needed.

- Skill: `tomevault-io/readme-maintainer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/readme-maintainer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/readme-maintainer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/readme-maintainer

---


# Readme Maintainer

## Overview

Maintain `README.md` as a code-adjacent artifact: grounded in the current repository state, clear for users, and safe from hallucinated commands. Use the active assistant model in this session; do not route through `readme-ai` provider APIs. Default to bilingual parity (English + Simplified Chinese) unless the user explicitly asks for single-language output.

## Workflow

1. Resolve target repo path:
- Default to current working directory if user does not specify a path.
- Use explicit path if the user provides one.
- Confirm `README.md` destination (`README.md` by default).

2. Collect project facts:
- Run `scripts/collect_repo_facts.sh <repo-path>`.
- Read existing `README.md` first (if present), then read only relevant source/config files.
- Prefer authoritative files: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Makefile`, and entrypoint modules.

3. Draft content with repository truth as source of record:
- Keep or improve useful existing sections.
- Add missing core sections only when supported by codebase facts.
- If data is unknown, state TODO/placeholder text explicitly instead of inventing details.
- If README is bilingual or user audience is mixed, draft mirrored English and Chinese sections with equivalent meaning and scope.

4. Apply update:
- Write directly to `README.md` unless user asks for preview file.
- Preserve user-specific sections where possible (`Contributing`, `Roadmap`, `Acknowledgements`) unless user asks for full rewrite.

5. Validate before finishing:
- Re-check all commands and paths against files in repo.
- Ensure install/run/test steps exist and are executable in principle.
- Run quick sanity checks when cheap (`rg` for referenced scripts/targets).
- For bilingual README, run `scripts/check_bilingual_readme.sh README.md` and fix missing paired headings.

6. Report changes:
- Summarize what sections changed and why.
- Note any assumptions or unresolved gaps.

## Required Constraints

- Use the current session model for generation and editing.
- Do not call external README generation providers or ask user for provider switching.
- Do not fabricate metrics, compatibility claims, or benchmark numbers.
- Do not claim commands work unless they are grounded in repo files.
- Default to bilingual output (`## English` and `## 简体中文`) for externally facing project README files.
- Keep English and Chinese sections synchronized: each required section in one language must have its counterpart in the other language unless user explicitly opts out.

## Output Shape

Prefer this structure, adapting to project reality:
- Project title + one-line value proposition
- Features / capabilities
- Install
- Quick start / usage
- Configuration (if applicable)
- Development and testing
- Project structure (short tree)
- Contributing / license

For bilingual mode (default), keep a mirrored section map:
- `### Project Description` <-> `### 项目说明`
- `### Features` <-> `### 功能特性`
- `### Quick Start` <-> `### 快速开始`
- `### Skill Catalog` <-> `### 技能目录`
- `### Project Structure` <-> `### 项目结构`
- `### Configuration` <-> `### 配置` (when environment variables or service setup are required)
- `### Development and Testing` <-> `### 开发与测试`
- `### Contributing` <-> `### 贡献指南`
- `### Maintenance Guide` <-> `### 维护指南`
- `### License` <-> `### 许可证`

Read `references/readme-checklist.md` when drafting.

## Commands

```bash
# Gather repo facts before editing README
scripts/collect_repo_facts.sh <repo-path>

# Validate bilingual section parity
scripts/check_bilingual_readme.sh README.md
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/lingengyuan) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-12 -->