SuperAPI AI 工具集

re0-readme

写作与研究

查看项目

更新于 11-09 16:50

技能介绍

用途

re0-readme 用于处理仓库文档中的“读者错位”问题:README.md 应当服务于决定是否及如何使用该仓库的人,AGENTS.md 应当服务于在仓库内工作的智能体(如目录结构、命令、检查门槛、约定)。技能的目标是让每条信息只出现在其目标读者所需的文件中;两个读者都需要的事实时,分别以适合各自读者的形式呈现(如 README 写人打开的地址,AGENTS.md 写智能体维护的配置),两份文件互不重复对方的过程,只做链接引用。

同时,该技能还负责校正宿主或注册表在打开这两份文件之前所展示的清单(如 package.json、.claude-plugin/ 与 .codex-plugin/ 插件文件、市场文件、各技能的 agents/openai.yaml),确保它们使用仓库的统一名称、指向仓库自身地址,并准确列出所发布的技能文件夹。若重命名只改到 README 而未同步清单,各宿主上仍会显示旧名称。

主要能力

  • 基于自带脚本审计仓库的 README、AGENTS.md 与清单文件,报告基线审计结果、类型及其来源,以及每条发现的规则编号、文件、行号与严重级别,并附保留清单及理由。
  • 支持仅审查模式:只报告建议的移动方案与保留清单,不做任何编辑;也支持改写模式:报告编辑后的文件、改写后审计结果及托管审计结果或未解决的失败。
  • 类型检测:默认从仓库文件推断类型(app/cli/library/skills),也可通过 --kind 指定;类型决定严重级别。
  • 支持将仓库 .gitignore 排除的点目录视为本地状态,并可通过 --loop-dir 追加本地状态文件夹名称。
  • 当仅有 CLAUDE.md 时,将其作为智能体指南读取,并报告缺失 AGENTS.md 的失败;改写模式可创建 AGENTS.md 或指向 CLAUDE.md 的链接。
  • 对清单进行对齐:统一仓库名称(npm 名称使用小写形式)、指向仓库自身地址、准确列出插件发布的技能文件夹、为每个技能提供 agents/openai.yaml 且默认提示命名为 $<skill>。
  • 托管界面审计:检查描述与 README 开头及声明是否一致、主题、主页权威性、社区资料缺口、README 大小及自定义社交预览图的尺寸与适用性。托管审计仅报告,提出更正建议;权衡得失的设置以可选项形式呈现,不作为发现,也不会导致运行失败。
  • 改写前可调用相关技能(如 ssotize、detool、re0-order、debloat、sip)辅助处理单一事实来源、术语替换、排序、精简与体验测试。

使用方式

在技能文件夹中运行审计脚本:

node scripts/audit.mjs [<repo-root>] [--kind app|cli|library|skills] [--loop-dir <name>]... [--host <owner/repo>] [--strict] [--json] [--rules]

  • --json 以单个 JSON 对象输出结果;--rules 打印每种类型下的全部规则编号及其严重级别。
  • 退出码:0 表示无失败发现;1 表示存在失败发现、--strict 下任意发现,或缺少 AGENTS.md;2 表示用法错误或输入不可读(未知类型、根目录不是目录、package.json 无法解析)。退出码 2 属于运行失败,而非审计未通过,应修正命令或输入后重试。
  • 典型流程:先运行审计保留基线;核对类型;结合上下文逐条阅读发现(匹配只是线索而非结论,需决定移动、改写或保留,并为保留项写明理由);若请求仅为审查则到此为止并报告,若请求为改写则继续。
  • 改写 README 时面向其读者、使用该读者所读语言(由仓库所有者或同类仓库确定,而非代码语言):开头一句话说明产品是什么,随后说明今天实际能做到什么(以度量呈现),给出可见结果或用法示例、最短可用安装步骤、支持环境、重要依赖及深入文档链接。若产品实际能力低于设计目标,应在靠前位置如实说明并给出度量,设计目标只作为目标陈述。列表表格中将分组列转为小节,状态用图标加文字表示且图例只出现一次。
  • 视觉类产品应先放真实产品图片:在场景字体、图片与数据加载完成后截图,发布前检查画面;产品支持手机等设备时,应在桌面截图旁展示其屏幕截图,并使用已提交的示例数据通过仓库脚本截取。
  • 改写 AGENTS.md 时面向智能体、默认使用英文(除非仓库约定指定其他语言):先说明哪类事实由哪份文档负责,再写仓库地图、运行命令、检查门槛及各自保护的内容、失败规则及其证据、文档约定与提交约定。
  • 改写后重新运行审计,并按目标读者的视角阅读两份文件与清单。
  • 运行 node scripts/audit.mjs --host <owner/repo> 审计托管界面。
  • 在批准停止前调用 sip 技能进行改写体验测试。
  • 最后提出将审计加入仓库检查列表的建议:以随附脚本副本形式加入并注明来源,使检查在全新克隆上可运行;不得指向仅存在于某台机器上的路径。是否采纳由人决定,批准前不加入检查列表或 CI。

适用场景

  • README 或 AGENTS.md 即将编写、刚编写完成或正在评审。
  • 怀疑某份文件中的某行内容实际服务于另一份文件的目标读者。
  • 需要确保插件、市场文件与技能清单在各宿主上名称、地址与技能列表一致。
  • 需要审计仓库在托管平台上的展示描述、主题、社区资料与社交预览图。

限制

  • 契约、账本、变更日志与发布说明不在处理范围内。
  • 仅审查请求只报告、不编辑;只有明确要求编写、修复或改写时才执行编辑。
  • 移除某一事实(且该事实无其他归宿)需人工批准;将审计加入检查列表或 CI、修改仓库随附脚本副本中的规则,均需人工明确批准,批准前作为建议报告。
  • 说明性例外不会改变退出码;被保留的失败发现仍为红色,不能以文字解释声称已通过。
  • 移动内容不得丢失:离开某文件的一行应落到另一文件、链接文档或带理由的保留清单中。
  • 编辑需安全:替换前确认目标行存在,遇不匹配报告 MISS,按 Unicode 安全方式编辑,逐处处理,不得一刀切。
  • 宿主没有 Skill 工具时,应直接阅读并遵循各已安装技能;若不可用,须报告缺失步骤且不得声称已运行。
  • 脚本负责规则表:应引用脚本、其参数与退出码,不得复述规则。