md-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown Documentation

Markdown 文档

Manage project documentation by verifying against actual codebase state. Emphasize verification over blind generation — analyze structure, files, and patterns before writing.

通过对照实际代码库状态管理项目文档。优先校验而非盲目生成——编写前先分析结构、文件和模式。

Portability

可移植性

AGENTS.md is the universal context file (works with Claude Code, Codex, Kilocode). If the project uses CLAUDE.md, treat it as a symlink to AGENTS.md or migrate content into AGENTS.md and create the symlink:

bash

undefined

AGENTS.md 是通用上下文文件（兼容 Claude Code、Codex、Kilocode）。如果项目使用 CLAUDE.md，请将其视为指向 AGENTS.md 的符号链接，或将内容迁移到 AGENTS.md 后创建符号链接：

bash

undefined

If CLAUDE.md exists and AGENTS.md doesn't

mv CLAUDE.md AGENTS.md && ln -sf AGENTS.md CLAUDE.md


When this skill references "context files", it means AGENTS.md (and CLAUDE.md if present as symlink).

mv CLAUDE.md AGENTS.md && ln -sf AGENTS.md CLAUDE.md


当本技能提及「上下文文件」时，指的是 AGENTS.md（以及作为符号链接存在的 CLAUDE.md，如果有的话）。

Workflows

工作流

Update Context Files

更新上下文文件

Verify and fix AGENTS.md against the actual codebase. See update-agents.md for the full verification workflow.

Read existing AGENTS.md, extract verifiable claims (paths, commands, structure, tooling)
Verify each claim against codebase (
```
ls
```
,
```
cat package.json
```
,
```
cat pyproject.toml
```
, etc.)
Fix discrepancies: outdated paths, wrong commands, missing sections, stale structure
Discover undocumented patterns (scripts, build tools, test frameworks not yet documented)
Report changes

对照实际代码库校验并修复 AGENTS.md。完整校验流程请参考 update-agents.md。

读取现有 AGENTS.md，提取可验证的声明（路径、命令、结构、工具链）
对照代码库校验每条声明（
```
ls
```
、
```
cat package.json
```
、
```
cat pyproject.toml
```
等）
修复不一致问题：过时的路径、错误的命令、缺失的章节、陈旧的结构
发现未记录的模式（尚未归档的脚本、构建工具、测试框架）
上报变更

Update README

更新 README

Generate or refresh README.md from project metadata and structure. See update-readme.md for section templates and language-specific patterns.

Detect language/stack from config files (package.json, pyproject.toml, composer.json)
Extract metadata: name, version, description, license, scripts
If README exists and
```
--preserve
```
: keep custom sections (About, Features), regenerate standard sections (Install, Usage)
Generate sections appropriate to project type (library vs application)
Report changes

根据项目元数据和结构生成或刷新 README.md。章节模板和语言特定模式请参考 update-readme.md。

从配置文件（package.json、pyproject.toml、composer.json）检测语言/技术栈
提取元数据：名称、版本、描述、许可证、脚本
如果 README 已存在且指定了
```
--preserve
```
参数：保留自定义章节（关于、特性），重新生成标准章节（安装、使用）
生成适配项目类型的章节（库 vs 应用）
上报变更

Update CONTRIBUTING

更新 CONTRIBUTING

Update existing CONTRIBUTING.md only — never auto-create. See update-contributing.md.

When updating, detect project conventions automatically:

Package manager from lock files (package-lock.json → npm, yarn.lock → yarn, pnpm-lock.yaml → pnpm, bun.lockb → bun)
Branch conventions from git history (feature/, fix/, chore/ prefixes)
Test commands from package.json scripts or pyproject.toml

仅更新已有的 CONTRIBUTING.md——禁止自动创建。参考 update-contributing.md。

更新时自动检测项目规范：

从锁文件识别包管理器（package-lock.json → npm、yarn.lock → yarn、pnpm-lock.yaml → pnpm、bun.lockb → bun）
从 git 历史识别分支规范（feature/、fix/、chore/ 前缀）
从 package.json 脚本或 pyproject.toml 识别测试命令

Update DOCS

更新 DOCS

DOCS.md

exists, treat it as API-level documentation (endpoints, function signatures, type definitions). Verify against actual code the same way as AGENTS.md. Never auto-create DOCS.md — only update existing.

如果存在

DOCS.md

，将其视为 API 级文档（接口、函数签名、类型定义）。按照和 AGENTS.md 相同的方式对照实际代码校验。禁止自动创建 DOCS.md——仅更新已有文件。

Initialize Context

初始化上下文

Create AGENTS.md from scratch for projects without documentation. See init-agents.md.

Analyze project: language, framework, structure, build/test tools
Generate terse, expert-to-expert context sections
Write AGENTS.md, create CLAUDE.md symlink

为没有文档的项目从零创建 AGENTS.md。参考 init-agents.md。

分析项目：语言、框架、结构、构建/测试工具
生成简洁的、面向专家的上下文章节
编写 AGENTS.md，创建 CLAUDE.md 符号链接

Arguments

参数

All workflows support:

```
--dry-run
```
: preview changes without writing
```
--preserve
```
: keep existing structure, fix inaccuracies only
```
--minimal
```
: quick pass, high-level structure only
```
--thorough
```
: deep analysis of all files

所有工作流都支持以下参数：

```
--dry-run
```
：预览变更而不写入文件
```
--preserve
```
：保留现有结构，仅修正不准确的内容
```
--minimal
```
：快速处理，仅生成高层级结构
```
--thorough
```
：深度分析所有文件

Backup Handling

备份处理

Before overwriting, back up existing files:

bash

cp AGENTS.md AGENTS.md.backup
cp README.md README.md.backup

Never delete backups automatically.

覆盖文件前，备份现有文件：

bash

cp AGENTS.md AGENTS.md.backup
cp README.md README.md.backup

禁止自动删除备份。

Writing Style

编写风格

Terse: omit needless words, lead with the answer
Imperative: "Build the project" not "The project is built"
Expert-to-expert: skip basic explanations, assume competence
Scannable: headings, lists, code blocks
Accurate: verify every command and path against codebase
Sentence case headings, no emoji headers
Actionable headings: "Set SAML before adding users" not "SAML configuration timing"
Collapse depth with
```
<details>
```
blocks instead of deleting it (blank line after
```
<summary>
```
required for GitHub rendering)

简洁：省略无用词汇，直入主题
祈使语气：使用「构建项目」而非「项目将被构建」
面向专家：跳过基础说明，假设读者具备相关能力
易扫描：使用标题、列表、代码块
准确：对照代码库校验每条命令和路径
标题使用句首大写，不使用表情符号
标题可落地：使用「添加用户前先设置SAML」而非「SAML配置时机」
用
```
<details>
```
块折叠深度内容而非直接删除（为适配 GitHub 渲染，
```
<summary>
```
后需要空一行）

README Anti-Patterns

README 反模式

Flag during

Update README

workflows:

Framework-first lead (explaining the tech stack before the problem it solves)
Jargon before definition (using project-specific terms without introduction)
Theory before try (architecture explanation before a working example)
Claims without evidence ("blazingly fast" with no benchmarks)

在「更新 README」工作流中需要标记以下问题：

优先介绍框架：在说明解决的问题之前先介绍技术栈
术语未定义：使用项目专属术语前未做介绍
先讲理论再给实践：在给出可运行示例之前先讲解架构
无依据的断言：没有基准测试支撑的「极速」之类的描述

Report Format

报告格式

After every operation, display a summary:

✓ Updated AGENTS.md
  - Fixed build command
  - Added new directory to structure

✓ Updated README.md
  - Added installation section
  - Updated badges

⊘ CONTRIBUTING.md not found (skipped)

每次操作后展示摘要：

✓ Updated AGENTS.md
  - Fixed build command
  - Added new directory to structure

✓ Updated README.md
  - Added installation section
  - Updated badges

⊘ CONTRIBUTING.md not found (skipped)