HomeJimu HarnessCommunityModelsResourcesDocumentationSkillAgentMCPTeamAbout us
Sign up / Sign in

Quick links

Jimu AI

Jimu AI — tools for building intelligent applications

Loading...
← Back to skills

write-skill-readme

v1.0.2
Bensz Conan

技能 README 生成器:基于 SKILL.md、配置、脚本和参考资料生成面向普通用户的 README 使用指南。 输出聚焦快速开始、典型场景、功能概述、输出说明和 FAQ,帮助技能在资源市场中更清晰地展示。

Writing技能文档README用户指南文档生成
↓ 2 downloads

name: write-skill-readme description: | 技能 README 生成器:基于 SKILL.md、配置、脚本和参考资料生成面向普通用户的 README 使用指南。 输出聚焦快速开始、典型场景、功能概述、输出说明和 FAQ,帮助技能在资源市场中更清晰地展示。 author: "Bensz Conan" license: "MIT" category: "writing" tags: "技能文档, README, 用户指南, 文档生成" source: "https://github.com/huangwb8/skills/tree/main/write-skill-readme" allowed-tools: "glob, read_file, search_file_content, write_file, replace, ask_user_question"

Write Skill README:技能用户指南生成器

适用场景

适用于以下任务:

  • 为某个 Skill 生成 README.md
  • 编写技能用户指南、使用说明、快速开始文档
  • 把技能的 SKILL.md 改写成普通用户能看懂的说明
  • 更新已有 README,使其更清晰、更适合资源市场展示

安全边界

默认只生成或更新目标技能目录下的 README.md。

  • 可以读取:SKILL.md、配置文件、脚本、参考文档、已有 README
  • 不要修改:SKILL.md、配置文件、脚本、参考文档
  • 如果用户明确要求修改技能本体,应先说明这已经超出 README 生成范围,再按用户的新要求处理
  • 不要把脚本中的危险命令、内部路径、私有令牌或平台绑定说明原样写入 README

输入要求

用户至少提供一个技能目录路径,或明确指出当前工作区中的某个技能。

如果目标不明确,先询问:

  1. 要为哪个技能生成 README?
  2. README 面向谁:普通用户、开发者、管理员还是市场审核者?
  3. 是否要覆盖已有 README?

工作流程

1. 分析技能结构

优先读取以下文件:

文件/目录 用途
SKILL.md 提取技能名称、触发条件、核心流程和输出要求
config.yaml / config.json 提取可配置参数和默认值
scripts/ 判断是否存在可选脚本用法,只记录安全、必要的用户用法
references/ 提取可面向用户解释的背景资料
README.md 如果已存在,判断是否更新而不是完全重写

读取脚本或参考资料时,只抽取用户需要理解的用法,不复制内部实现细节。

2. 判断 README 类型

类型 特征 文档重点
功能型 主要通过自然语言触发 快速开始、场景示例、输出说明
工具型 主要依赖脚本或命令 前置条件、参数、命令示例、输出文件
混合型 自然语言优先,脚本可选 推荐用法在前,脚本作为备选放后面

3. 生成 README 结构

默认生成以下章节,按技能实际情况裁剪:

# {技能名称} — 用户使用指南

本 README 面向使用者,说明如何触发并正确使用 `{技能名称}`。

## 快速开始

```text
请使用 {skill_name} skill {完成具体任务}
输入:{输入内容或路径}
输出:{输出文件、格式或结果}
```

## 适用场景

| 你的需求 | 推荐用法 |
| --- | --- |
| ... | ... |

## 功能概述

| 能力 | 说明 |
| --- | --- |
| ... | ... |

## 使用示例

### 示例 1:最小可用

```text
...
```

### 示例 2:带参数约束

```text
...
```

## 输出说明

- `{文件名}`:{说明}

## 配置选项

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| ... | ... | ... |

## 常见问题

### Q:...

A:...

4. 写作要求

  • 使用第二人称,避免内部实现视角
  • 快速开始必须短、可复制、能覆盖 80% 常见需求
  • 示例按“最小可用 → 进阶 → 特殊场景”排列
  • 复杂选择用表格表达,不写长篇说教
  • 文件、路径、命令、参数使用代码格式
  • 不暴露不适用于当前平台的安装路径、外部工具绑定或私有工作流

5. 写入或更新 README

如果目录中没有 README.md,直接写入新文件。

如果已有 README.md:

  1. 先读取原文,保留仍然正确的信息
  2. 删除过期、平台绑定或误导性内容
  3. 用新结构补齐快速开始、示例、输出说明和 FAQ
  4. 写入前简要说明覆盖范围

完成前自检

交付前检查:

  • README 是否能让第一次使用的人直接上手
  • 快速开始是否包含输入和输出
  • 是否误写了不存在的工具、平台、安装路径或外部服务
  • 是否复制了脚本内部实现细节而不是用户用法
  • 链接、相对路径、文件名是否准确
  • 若修改了已有 README,是否保留了仍然有效的用户信息