md-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown Documentation Management

Markdown文档管理

Overview

概述

Manage project documentation for Claude Code workflows including context files, READMEs, and agent instructions. This skill provides structured automation for maintaining accurate, up-to-date documentation that aligns with actual codebase structure and functionality. Use this skill when initializing new projects, updating existing documentation, or ensuring context files accurately reflect current code.

The skill emphasizes verification and validation over blind generation—analyze the actual codebase structure, file contents, and patterns before creating or updating documentation. All generated content should be terse, imperative, and expert-to-expert rather than verbose or tutorial-style.

管理Claude Code工作流的项目文档，包括上下文文件、README和Agent说明。本技能提供结构化自动化能力，用于维护与实际代码库结构和功能一致的准确、最新的文档。在初始化新项目、更新现有文档或确保上下文文件准确反映当前代码状态时，可使用本技能。

本技能强调验证与校验而非盲目生成——在创建或更新文档前，需分析实际代码库结构、文件内容和模式。所有生成的内容应简洁、命令式且采用专家对专家的风格，而非冗长的教程式内容。

Prerequisites

前提条件

Before using any documentation workflow, verify basic project structure:

bash

git rev-parse --git-dir

Ensure the output confirms you are in a git repository. If not initialized, documentation workflows may still proceed but git-specific features will be skipped.

For update workflows, verify target files exist:

bash

ls -la CLAUDE.md AGENTS.md DOCS.md README.md CONTRIBUTING.md

Check which files are present before attempting updates. Missing files will show errors, which helps identify what needs initialization. Note that DOCS.md is optional and only relevant for projects with APIs or public interfaces. CONTRIBUTING.md is optional and only relevant if the repo already defines contribution guidance.

使用任何文档工作流前，请验证基本项目结构：

bash

git rev-parse --git-dir

确保输出确认你处于git仓库中。若未初始化，文档工作流仍可继续，但会跳过git特定功能。

对于更新工作流，请验证目标文件是否存在：

bash

ls -la CLAUDE.md AGENTS.md DOCS.md README.md CONTRIBUTING.md

在尝试更新前检查哪些文件存在。缺失的文件会显示错误，这有助于识别需要初始化的内容。注意DOCS.md是可选的，仅对包含API或公共接口的项目相关。CONTRIBUTING.md也是可选的，仅当仓库已定义贡献指南时相关。

Update Context Files

更新上下文文件

Verify and fix CLAUDE.md, AGENTS.md, and optionally DOCS.md and CONTRIBUTING.md against the actual codebase. This workflow reads existing context files, analyzes the codebase structure, identifies discrepancies, and updates documentation to match reality. DOCS.md and CONTRIBUTING.md are only processed if they exist in the repository.

对照实际代码库验证并修复CLAUDE.md、AGENTS.md，以及可选的DOCS.md和CONTRIBUTING.md。此工作流会读取现有上下文文件，分析代码库结构，识别差异，并更新文档以匹配实际情况。仅当仓库中存在DOCS.md和CONTRIBUTING.md时才会处理它们。

Workflow Steps

工作流步骤

Parse Arguments

Support the following arguments:

```
--dry-run
```
: Show what would change without writing files
```
--preserve
```
: Keep existing content structure, only fix inaccuracies
```
--thorough
```
: Perform deep analysis of all files (slower but comprehensive)
```
--minimal
```
: Quick verification focusing on high-level structure only

Verify Git Repository

Confirm working directory is a git repository. If not, warn the user but proceed with limitations (cannot analyze git history or branches).

Read Existing Context Files

Read current CLAUDE.md, AGENTS.md, DOCS.md, and CONTRIBUTING.md (if present) contents:

bash

cat CLAUDE.md
cat AGENTS.md
cat DOCS.md         # if exists
cat CONTRIBUTING.md # if exists

Parse the structure and extract documented information including:

Project description and purpose
File structure and organization
Build and test commands
Custom tooling or scripts
Agent configurations and triggers
API endpoints and methods (from DOCS.md)
Function signatures and parameters (from DOCS.md)
Type definitions and interfaces (from DOCS.md)
Contribution workflow and guidelines (from CONTRIBUTING.md)
Code review process and standards (from CONTRIBUTING.md)

Analyze Codebase

Scan the project to gather accurate information:

Directory structure (
```
ls -la
```
,
```
tree
```
if available)
Package configuration (
```
package.json
```
,
```
pyproject.toml
```
,
```
Cargo.toml
```
, etc.)
Build scripts and commands
Test frameworks and configurations
README badges and metadata

For

--thorough

mode, also analyze:

File content patterns (imports, exports, interfaces)
Code organization conventions
Dependency relationships

Identify Discrepancies

Compare documented information against actual codebase:

Outdated file paths or structure
Incorrect build commands
Missing or removed features
Deprecated dependencies
Stale agent configurations
Outdated API endpoints or routes (DOCS.md)
Changed function signatures (DOCS.md)
Modified type definitions (DOCS.md)
Outdated contribution guidelines (CONTRIBUTING.md)
Stale branch naming or PR process (CONTRIBUTING.md)

Create Backups

Before overwriting, create backup files:

bash

cp CLAUDE.md CLAUDE.md.backup
cp AGENTS.md AGENTS.md.backup
test -f DOCS.md && cp DOCS.md DOCS.md.backup
test -f CONTRIBUTING.md && cp CONTRIBUTING.md CONTRIBUTING.md.backup

Update Context Files

Write corrected versions maintaining the existing structure when

--preserve

is used, or reorganizing for clarity when not. For

--dry-run

, display the diff without writing:

bash

diff -u CLAUDE.md.backup CLAUDE.md

Generate Report

Display a summary of changes.

When DOCS.md exists:

✓ Updated CLAUDE.md
  - Fixed outdated build command
  - Added new /api directory to structure

✓ Updated AGENTS.md
  - Updated test-runner trigger pattern

✓ Updated DOCS.md
  - Fixed outdated endpoint path /api/v1/users
  - Updated function signature for createUser()

✓ Updated CONTRIBUTING.md
  - Updated branch naming convention
  - Fixed outdated PR template reference

When optional files are absent:

✓ Updated CLAUDE.md
  - Fixed outdated build command

✓ Updated AGENTS.md
  - Updated test-runner trigger pattern

⊘ DOCS.md not found (skipped)
⊘ CONTRIBUTING.md not found (skipped)

For the complete update context files workflow with verification strategies, diff examples, and edge cases, refer to

references/update-agents.md

解析参数

支持以下参数：

```
--dry-run
```
：显示将要进行的更改但不写入文件
```
--preserve
```
：保留现有内容结构，仅修复不准确之处
```
--thorough
```
：对所有文件进行深度分析（速度较慢但全面）
```
--minimal
```
：快速验证，仅关注高层级结构

验证Git仓库

确认工作目录处于git仓库中。若未处于，向用户发出警告但仍继续执行，不过会有功能限制（无法分析git历史或分支）。

读取现有上下文文件

读取当前CLAUDE.md、AGENTS.md、DOCS.md和CONTRIBUTING.md（若存在）的内容：

bash

cat CLAUDE.md
cat AGENTS.md
cat DOCS.md         # 若存在
cat CONTRIBUTING.md # 若存在

解析结构并提取已记录的信息，包括：

项目描述和用途
文件结构和组织方式
构建和测试命令
自定义工具或脚本
Agent配置和触发条件
API端点和方法（来自DOCS.md）
函数签名和参数（来自DOCS.md）
类型定义和接口（来自DOCS.md）
贡献工作流和指南（来自CONTRIBUTING.md）
代码审查流程和标准（来自CONTRIBUTING.md）

分析代码库

扫描项目以收集准确信息：

目录结构（
```
ls -la
```
，若可用则用
```
tree
```
）
包配置（
```
package.json
```
、
```
pyproject.toml
```
、
```
Cargo.toml
```
等）
构建脚本和命令
测试框架和配置
README徽章和元数据

在

--thorough

模式下，还会分析：

文件内容模式（导入、导出、接口）
代码组织约定
依赖关系

识别差异

将已记录的信息与实际代码库进行对比：

过时的文件路径或结构
不正确的构建命令
缺失或已移除的功能
已弃用的依赖
过时的Agent配置
过时的API端点或路由（DOCS.md）
已更改的函数签名（DOCS.md）
已修改的类型定义（DOCS.md）
过时的贡献指南（CONTRIBUTING.md）
过时的分支命名或PR流程（CONTRIBUTING.md）

创建备份

在覆盖文件前，创建备份文件：

bash

cp CLAUDE.md CLAUDE.md.backup
cp AGENTS.md AGENTS.md.backup
test -f DOCS.md && cp DOCS.md DOCS.md.backup
test -f CONTRIBUTING.md && cp CONTRIBUTING.md CONTRIBUTING.md.backup

更新上下文文件

当使用

--preserve

参数时，在保持现有结构的前提下写入修正后的版本；若未使用该参数，则重新组织内容以提升清晰度。对于

--dry-run

模式，显示差异但不写入：

bash

diff -u CLAUDE.md.backup CLAUDE.md

生成报告

显示更改摘要。

当DOCS.md存在时：

✓ 更新了CLAUDE.md
  - 修复了过时的构建命令
  - 在结构中添加了新的/api目录

✓ 更新了AGENTS.md
  - 更新了test-runner触发模式

✓ 更新了DOCS.md
  - 修复了过时的端点路径/api/v1/users
  - 更新了createUser()的函数签名

✓ 更新了CONTRIBUTING.md
  - 更新了分支命名约定
  - 修复了过时的PR模板引用

当可选文件不存在时：

✓ 更新了CLAUDE.md
  - 修复了过时的构建命令

✓ 更新了AGENTS.md
  - 更新了test-runner触发模式

⊘ 未找到DOCS.md（已跳过）
⊘ 未找到CONTRIBUTING.md（已跳过）

如需包含验证策略、差异示例和边缘情况的完整更新上下文文件工作流，请参考

references/update-agents.md

。

Update README

更新README

Generate or update README.md based on project structure, package metadata, and codebase analysis. This workflow creates comprehensive, accurate READMEs that reflect the actual state of the project.

基于项目结构、包元数据和代码库分析生成或更新README.md。此工作流创建全面、准确的README，反映项目的实际状态。

Workflow Steps

工作流步骤

Parse Arguments

Support the following arguments:

```
--dry-run
```
: Preview README content without writing
```
--preserve
```
: Keep existing sections, only update outdated information
```
--minimal
```
: Generate minimal README (title, description, installation, usage)
```
--full
```
: Generate comprehensive README with all optional sections

Analyze Project Structure

Gather information from multiple sources:

bash

undefined

解析参数

支持以下参数：

```
--dry-run
```
：预览README内容但不写入
```
--preserve
```
：保留现有章节，仅更新过时信息
```
--minimal
```
：生成极简版README（标题、描述、安装、使用）
```
--full
```
：生成包含所有可选章节的完整版README

分析项目结构

从多个来源收集信息：

bash

undefined

Package metadata

包元数据

cat package.json cat pyproject.toml cat Cargo.toml

Git information

Git信息

git remote get-url origin git describe --tags

Directory structure

目录结构

ls -la


Extract:

- Project name and description
- Version number
- Repository URL
- License
- Dependencies
- Scripts/commands

**Read Existing README**

If README.md exists and `--preserve` is used:

```bash
cat README.md

Parse existing sections to preserve custom content while updating technical details.

Read CONTRIBUTING.md (Optional)

If CONTRIBUTING.md exists, read it and treat it as the source of truth for contribution guidance. Do not duplicate detailed contribution steps in README; link to CONTRIBUTING.md instead.

bash

test -f CONTRIBUTING.md && cat CONTRIBUTING.md

Create Backup

Before overwriting existing README:

bash

cp README.md README.md.backup

Generate README Content

Create structured content with appropriate sections:

Title and badges (version, license, build status)
Description (concise project summary)
Installation (package manager commands)
Usage (basic examples)
Development (build, test, lint commands)
Contributing (if applicable; link to CONTRIBUTING.md when it exists)
License (based on package metadata)

For

--minimal

mode, include only title, description, installation, and usage.

For

--full

mode, also include:

API documentation
Examples directory listing
Deployment instructions
Troubleshooting section
Credits and acknowledgments

Write README

Save the generated content. For

--dry-run

, display without writing.

Generate Report

Display summary:

✓ Updated README.md
  - Added installation section
  - Updated build commands to match package.json
  - Added badges for license and version

For the complete update README workflow with section templates, metadata extraction strategies, and formatting examples, refer to

references/update-readme.md

ls -la


提取：

- 项目名称和描述
- 版本号
- 仓库URL
- 许可证
- 依赖项
- 脚本/命令

**读取现有README**

若README.md存在且使用了`--preserve`参数：

```bash
cat README.md

解析现有章节以保留自定义内容，同时更新技术细节。

读取CONTRIBUTING.md（可选）

若CONTRIBUTING.md存在，读取该文件并将其作为贡献指南的权威来源。不要在README中重复详细的贡献步骤；而是链接到CONTRIBUTING.md。

bash

test -f CONTRIBUTING.md && cat CONTRIBUTING.md

创建备份

在覆盖现有README前：

bash

cp README.md README.md.backup

生成README内容

创建具有适当章节的结构化内容：

标题和徽章（版本、许可证、构建状态）
描述（简洁的项目摘要）
安装（包管理器命令）
使用（基础示例）
开发（构建、测试、 lint命令）
贡献（若适用；当CONTRIBUTING.md存在时链接到该文件）
许可证（基于包元数据）

对于

--minimal

模式，仅包含标题、描述、安装和使用。

对于

--full

模式，还包含：

API文档
示例目录列表
部署说明
故障排除章节
致谢和鸣谢

写入README

保存生成的内容。对于

--dry-run

模式，仅显示内容但不写入。

生成报告

显示摘要：

✓ 更新了README.md
  - 添加了安装章节
  - 更新了构建命令以匹配package.json
  - 添加了许可证和版本徽章

如需包含章节模板、元数据提取策略和格式示例的完整更新README工作流，请参考

references/update-readme.md

。

Update CONTRIBUTING

更新贡献指南

Update CONTRIBUTING.md based on current codebase tooling and workflows. This workflow only runs when CONTRIBUTING.md already exists in the repository. If CONTRIBUTING.md is absent, skip this workflow entirely—do not auto-create contribution guidelines.

基于当前代码库工具和工作流更新CONTRIBUTING.md。仅当仓库中已存在CONTRIBUTING.md时才会运行此工作流。 若CONTRIBUTING.md不存在，完全跳过此工作流——不要自动创建贡献指南。

Prerequisite Check

前提条件检查

Before proceeding, verify the file exists:

bash

test -f CONTRIBUTING.md && echo "exists" || echo "missing"

If missing, report to the user and stop. Do not create CONTRIBUTING.md unless explicitly requested.

在继续前，验证文件是否存在：

bash

test -f CONTRIBUTING.md && echo "exists" || echo "missing"

若文件缺失，向用户报告并停止。除非明确要求，否则不要创建CONTRIBUTING.md。

Workflow Steps

工作流步骤

Parse Arguments

Support the following arguments:

```
--dry-run
```
: Show what would change without writing files
```
--preserve
```
: Maximum preservation; only fix broken commands/links
```
--thorough
```
: Deep analysis; verify all links and commands work

Read Existing CONTRIBUTING.md

bash

cat CONTRIBUTING.md

Parse the document structure:

Section headings and organization
Code blocks with commands
URLs and file path references
Mentioned tooling (test runners, linters, formatters)

Gather Codebase Intelligence

Detect current tooling and compare against documented content:

Package manager (npm, pnpm, yarn, bun) from lock files
Available scripts from package.json/Makefile/justfile
Branch conventions (main vs master)
Linting/formatting tools in use

Identify Discrepancies

Compare documented information against actual codebase:

Outdated CLI commands (npm → pnpm)
Incorrect branch references (master → main)
Broken links to issue templates or docs
Stale tooling references (Jest → Vitest)

Update Content

Fix technical inaccuracies while preserving:

Contribution policies (CLA, DCO, licensing)
Review processes and expectations
Code of conduct references
Governance decisions

Generate Report

Display summary:

✓ Updated CONTRIBUTING.md
  - Fixed package manager: npm → pnpm
  - Corrected branch reference: master → main
  - Updated test command

⊘ Policy sections preserved (CLA, review process)

For the complete update CONTRIBUTING workflow with verification strategies and examples, refer to

references/update-contributing.md

解析参数

支持以下参数：

```
--dry-run
```
：显示将要进行的更改但不写入文件
```
--preserve
```
：最大程度保留内容；仅修复无效的命令/链接
```
--thorough
```
：深度分析；验证所有链接和命令是否有效

读取现有CONTRIBUTING.md

bash

cat CONTRIBUTING.md

解析文档结构：

章节标题和组织方式
包含命令的代码块
URL和文件路径引用
提及的工具（测试运行器、lint工具、格式化工具）

收集代码库信息

检测当前使用的工具并与已记录的内容进行对比：

包管理器（从锁文件判断npm、pnpm、yarn、bun）
package.json/Makefile/justfile中的可用脚本
分支约定（main vs master）
正在使用的lint/格式化工具

识别差异

将已记录的信息与实际代码库进行对比：

过时的CLI命令（npm → pnpm）
不正确的分支引用（master → main）
指向问题模板或文档的无效链接
过时的工具引用（Jest → Vitest）

更新内容

修复技术不准确之处，同时保留：

贡献政策（CLA、DCO、许可证）
审查流程和期望
行为准则引用
治理决策

生成报告

显示摘要：

✓ 更新了CONTRIBUTING.md
  - 修复了包管理器：npm → pnpm
  - 修正了分支引用：master → main
  - 更新了测试命令

⊘ 保留了政策章节（CLA、审查流程）

如需包含验证策略和示例的完整更新贡献指南工作流，请参考

references/update-contributing.md

。

Initialize Context

初始化上下文

Create project-specific CLAUDE.md from scratch based on codebase analysis. This workflow is ideal for new projects or repositories lacking context documentation.

基于代码库分析从头创建项目特定的CLAUDE.md。此工作流非常适合新项目或缺乏上下文文档的仓库。

Workflow Steps

工作流步骤

Parse Arguments

Support the following arguments:

```
--dry-run
```
: Preview generated content without writing
```
--minimal
```
: Create minimal context file (project description, structure)
```
--full
```
: Create comprehensive context file with all relevant sections

Verify No Existing CLAUDE.md

Check if CLAUDE.md already exists:

bash

test -f CLAUDE.md && echo "exists" || echo "missing"

If exists, warn the user and suggest using the update workflow instead. Allow override with

--force

flag.

Analyze Project

Gather comprehensive information:

Language and framework (detect from files and package configs)
Directory structure and organization patterns
Build system (npm, cargo, poetry, gradle, etc.)
Test framework (jest, pytest, cargo test, etc.)
Linting and formatting tools
Environment variables or configuration files

Generate CLAUDE.md Content

Create structured sections:

markdown

undefined

解析参数

支持以下参数：

```
--dry-run
```
：预览生成的内容但不写入
```
--minimal
```
：创建极简版上下文文件（项目描述、结构）
```
--full
```
：创建包含所有相关章节的完整版上下文文件

验证无现有CLAUDE.md

检查CLAUDE.md是否已存在：

bash

test -f CLAUDE.md && echo "exists" || echo "missing"

若已存在，向用户发出警告并建议使用更新工作流。允许使用

--force

参数覆盖。

分析项目

收集全面信息：

语言和框架（从文件和包配置检测）
目录结构和组织模式
构建系统（npm、cargo、poetry、gradle等）
测试框架（jest、pytest、cargo test等）
Lint和格式化工具
环境变量或配置文件

生成CLAUDE.md内容

创建结构化章节：

markdown

undefined

Context

上下文

Brief project description and purpose.

简短的项目描述和用途。

Structure

结构

Directory organization and key files.

目录组织方式和关键文件。

Build

构建

Commands for building the project.

项目构建命令。

Test

测试

Commands for running tests.

运行测试的命令。

Development

开发

Conventions, patterns, and workflows.


Adapt sections based on project type. For `--minimal`, include only Context and Structure. For `--full`, add all applicable sections including deployment, troubleshooting, and custom tooling.

**Write CLAUDE.md**

Save generated content. For `--dry-run`, display without writing.

**Generate Report**

Display summary:

✓ Created CLAUDE.md

Detected Next.js project
Added npm scripts from package.json
Documented project structure
Added testing section for Jest


For the complete initialize context workflow with language-specific templates, detection strategies, and customization options, refer to `references/init-agents.md`.

约定、模式和工作流。


根据项目类型调整章节。对于`--minimal`模式，仅包含上下文和结构章节。对于`--full`模式，添加所有适用章节，包括部署、故障排除和自定义工具。

**写入CLAUDE.md**

保存生成的内容。对于`--dry-run`模式，仅显示内容但不写入。

**生成报告**

显示摘要：

✓ 创建了CLAUDE.md

检测到Next.js项目
从package.json添加了npm脚本
记录了项目结构
添加了Jest测试章节


如需包含语言特定模板、检测策略和自定义选项的完整初始化上下文工作流，请参考`references/init-agents.md`。

DOCS.md Initialization

DOCS.md初始化

DOCS.md is optional and not created by default. Create DOCS.md manually when the project has:

Public API endpoints requiring documentation
Exported functions or classes intended for external use
Complex type definitions users need to understand

The update context workflow will suggest creating DOCS.md if it detects significant APIs without corresponding documentation.

DOCS.md是可选的，默认不会创建。当项目具有以下内容时，手动创建DOCS.md：

需要文档的公共API端点
供外部使用的导出函数或类
用户需要理解的复杂类型定义

若检测到大量API但无对应文档，更新上下文工作流会建议创建DOCS.md。

Additional Resources

其他资源

For detailed workflows, examples, and implementation guidance, refer to these reference documents:

references/common-patterns.md
- Argument parsing, backup handling, writing style, report formatting, file detection, and metadata extraction
references/update-agents.md
- Complete context file update workflow including verification strategies, diff generation, and discrepancy detection
references/update-readme.md
- Complete README update workflow including section templates, metadata extraction, and formatting conventions
references/update-contributing.md
- Complete CONTRIBUTING.md update workflow including scope, templates, and validation (only when CONTRIBUTING.md exists)
references/init-agents.md
- Complete context initialization workflow including language-specific templates, detection strategies, and customization options

These references provide implementation details, code examples, and troubleshooting guidance for each workflow type.

如需详细的工作流、示例和实现指南，请参考以下参考文档：

references/common-patterns.md
- 参数解析、备份处理、写作风格、报告格式、文件检测和元数据提取
references/update-agents.md
- 完整的上下文文件更新工作流，包括验证策略、差异生成和差异检测
references/update-readme.md
- 完整的README更新工作流，包括章节模板、元数据提取和格式约定
references/update-contributing.md
- 完整的CONTRIBUTING.md更新工作流，包括范围、模板和验证（仅当CONTRIBUTING.md存在时）
references/init-agents.md
- 完整的上下文初始化工作流，包括语言特定模板、检测策略和自定义选项

这些参考文档提供了每个工作流类型的实现细节、代码示例和故障排除指南。