mcpField
R
readme

readme

github.com/jimweller开发45 次安装
代码仓库

关于 readme

readme 是一项文档技能，可依据对话上下文和项目内容创建或更新 README.md。它强调按目录界定文档范围、核对代码与变更，并采用统一的 README 结构。

主要功能

  1. 01更新项目中的 README.md
  2. 02按目录树限定各 README 范围
  3. 03检查变更与对话上下文
  4. 04遵循既定 README 大纲
  5. 05建议编辑后运行 Markdown 检查

适用场景

  1. 01代码变更后更新文档
  2. 02分别记录嵌套组件
  3. 03判断 README 是否需要更新

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jimweller/clanker-skills --skill readme

安装后在 Claude Code 中输入/readme确认已加载。

详细介绍

STARTER_CHARACTER = 📓

文档编写

根据当前对话上下文和文件夹内容编写 Markdown 内容。

README 是面向人类用户的当前状态说明，不是变更日志、决策日志或历史记录。切勿记录历史信息或曾经做出的选择，只记录编写 README 时的当前规范。

相关技能

  • Markdown 规则和语法请使用 md-syntax 技能（/md-syntax、$md-syntax）
  • 编写惯例和写作风格请使用 md-style 技能（/md-style、$md-style）
  • 编写完成后，对文件使用 md-lint 技能（/md-lint、$md-lint）进行格式化和检查

范围

查找项目中的所有 README.md 文件并逐一更新。 README 所在目录及其下级目录（同级目录和子目录）均属于其内容范围，绝不包含上级目录。注意子目录层级、范围和边界上下文。不同层级的文档之间不得混淆概念。每份 README 只涵盖其所在目录及下级目录，不涉及父级目录的问题。

如果用户提供了具体指导或关注重点，请在决定文档强调哪些内容时纳入这些上下文。

收集上下文

对找到的每份 README，限定在其所在目录范围内：

  1. 阅读现有 README（如果存在）
  2. 计算自上次修改 README 以来的变更。包括已提交、已暂存、未暂存和未跟踪的工作：
TARGET_README=<path to the README being updated>
TARGET_DIR=$(dirname "$TARGET_README")

BASELINE=$(git log -1 --format=%H -- "$TARGET_README" 2>/dev/null)
[ -z "$BASELINE" ] && BASELINE=$(git rev-list --max-parents=0 HEAD 2>/dev/null)
HEAD_SHA=$(git rev-parse --verify -q HEAD)

if [ -n "$BASELINE" ] && [ "$BASELINE" != "$HEAD_SHA" ]; then
  git log --oneline "$BASELINE"..HEAD -- "$TARGET_DIR"
  git diff "$BASELINE" --stat -- "$TARGET_DIR"
  git diff "$BASELINE" -- "$TARGET_DIR"
elif [ -n "$HEAD_SHA" ]; then
  git show --stat HEAD -- "$TARGET_DIR"
  git diff HEAD --stat -- "$TARGET_DIR"
  git diff HEAD -- "$TARGET_DIR"
fi

git status --short -- "$TARGET_DIR"

--stat 必须放在 -- 之前。放在 -- 之后时，Git 会将其作为路径规格读取，并静默输出完整差异，而不是摘要。

先查看 --stat 摘要，再决定是否运行完整差异。README 没有自己的提交记录时，会回退到根提交，因此完整差异可能包含该目录的全部历史；在中型仓库中可能有数千行。摘要较大时，跳过完整差异，直接阅读变更文件。

差异中没有 ..HEAD，因此它涵盖基准版本到工作树的全部内容，包括已暂存和未暂存的编辑。这些分支涵盖四种情况：README 有自己的提交记录、README 没有自己的提交记录、仓库唯一的提交是根提交，以及仓库完全没有提交。若缺少这些分支，基准版本为空或等同于 HEAD 时，所有命令都会不返回任何内容，技能就会错误地得出无需记录任何内容的结论。

git status --short 会在一个视图中列出已暂存、未暂存和未跟踪的路径。未跟踪文件显示为 ??，其内容不会出现在任何差异中，因此要直接读取这些文件。整个过程中都会排除与 .gitignore 匹配的文件。

  1. 探索该目录层级及其以下的代码库
  2. 查看对话历史中相关的决策、变更或经验教训
  3. 根据差异和对话上下文确定需要更新的章节。对照文档核实代码，并对照代码核实文档。

如果没有任何变更需要更新 README，请说明这一点，然后继续。

README.md 大纲

README.md 的章节顺序和内容。根据目标项目填写每个章节。项目没有相关内容时，省略该章节。

  • # Title 和不超过五句话的概述
  • 可选图片或视频
  • ## Architecture - 以项目组件为条目列出，并说明各自用途
  • ## Prerequisites - 所需的账户、密钥、凭据、工具、运行时、命令行界面，并说明各自用途
  • ## Project Structure - 仅列出文件夹，不列文件，并用一句话说明各自用途
  • ## Installation - 安装项目的命令
  • ## Usage - 运行项目的命令
  • ## Testing - 项目没有测试时省略

目标长度少于 500 行。较长的 README 应拆分，将详细内容移入代码旁边的嵌套 README。

结构
# Title

Brief overview. No more than five sentences.


<img src="demo.png" alt="Demo" width="800"/>

## Architecture

High level components and purpose

- Component - purpose
- Component - purpose

## Prerequisites

- Prerequisite - description and reason (accounts, keys, credentials, tools, runtimes, CLIs)

## Project Structure

Show folder structure. Don't include files.

```text
project/
├── src/
│   ├── component-a/     # purpose - see src/component-a/README.md
│   └── component-b/     # purpose - see src/component-b/README.md
├── scripts/             # purpose
└── tests/               # purpose
```

## Installation

```bash
# how the project is installed
<install command>
```

## Usage

```bash
# how the project is run
<run command>
```

## Testing

```bash
# how the tests are run
<test command>
```

评论

支持 Markdown