Composio 文档语感审计指南用 good-docs-audit Skill 把技术文档统一到同一把尺子下【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio技术文档最容易出的问题不是事实错误而是语感漂移同一份文档里一会儿对读者说you一会儿退到第三人称the user标题一会儿句首大写、一会儿全词大写代码标识符有时加反引号、有时裸奔。Composio 仓库在 .agents/skills/good-docs-audit/SKILL.md 中内置了一个专门的审计 Skill用一套固定的风格规则rubric去逐行检查文档、指南、README 或任意文本块并输出带file:line定位的结构化违规报告。读完本文你将掌握这套审计流程的完整步骤、12 项优先级检查清单、报告格式以及仓库中保证该 Skill 本身不被改坏的工程化校验机制。这个 Skill 是什么什么时候该用它good-docs-audit的定位在 SKILL.md 的 frontmatter 中写得很清楚审计Audit一份文档、指南、README 或文本块对照good-docs-writing风格指南报告违规。它的触发场景是用户要求review、critique、lint 或检查文档的语气和口吻SKILL.md 第 3 行输出的是结构化 findings 报告包含file:line、违规规则、原文引用和建议改写。两个 Skill 的分工明确good-docs-writing负责写作按规则起草新文档或改写旧文案good-docs-audit负责审查检查已有文字是否偏离该语音voice只报告不改稿。在仓库的 AGENTS.md 路由说明中这两者被并列登记good-docs-writing: drafting or revising docs prose in the house writing voice 和 good-docs-audit: reviewing existing docs or prose against that voice and reporting violations。也就是说这套 Skill 已经接入仓库级的 Agent 路由体系是 Composio 文档工作流的一环。SKILL.md 还强调了一个默认行为边界默认只报告report only不编辑文件只有用户明确要求 fix、rewrite 或 apply 时才动手SKILL.md 第 8 行。这保证了审计动作本身不会意外污染文档内容。审计的尺子good-docs-writing 风格指南审计必须有标准可依。good-docs-audit的第一条不可妥协原则就是先读good-docs-writing及其references/style-guide.md这些规则是评分标准rubric本 Skill 只是执行流程SKILL.md 第 14 行。评分标准的核心规则见 .agents/skills/good-docs-writing/references/style-guide.md按六个类别组织Voice Tone语感与语气把读者称为you不用the user或one自信、直白不模棱两可也不推销腔先讲 why 再讲 how自然使用缩略形式you dontwont允许偶尔的个性和温度但绝不油滑。Structure结构第一句就定义概念或陈述收益不做清嗓子铺垫按概念 → 简单示例 → 进阶场景 → 踩坑渐进展开尽早给出最小可运行示例段落保持短善用列表和编号步骤。Terminology术语核心名词作为专有概念大写如 App、Function、Image、Volume优先用精确的技术词而非含糊表达cold startautoscaler禁止营销浮夸词seamlesslypowerfulrobustcutting-edge。Punctuation标点禁用 em-dash这是硬规则用句号、逗号、冒号或括号替代使用牛津逗号所有代码标识符、命令、参数、路径、文件名必须加反引号缩写和硬件名按惯例大写GPU、ASGI、A100。Code examples代码示例先给完整可运行片段imports、装饰器、函数俱全不让读者拿到无法粘贴的碎片示例保持最小注释只放在行为不明显处展示真实的 CLI 调用形式$、%、提示符某个 flag 是footgun时紧跟示例说明。Formatting格式单篇文档内标题大小写风格一致concept 类用 sentence casereference 类用 title case选定后不漂移标题要具体描述性警告、注意事项、受限功能、beta 状态用 callout 呈现而非埋进正文用描述性锚文本做链接。这套尺子的家谱也很明确style-guide.md 开篇注明this guide is derived from Modals documentation voice每一条规则都配了 Modal 文档的真实例句作为证据。审计流程五步走.agents/skills/good-docs-audit/references/audit-process.md 定义了标准流程共五步先读good-docs-writingSkill确保对着当前规则Voice、Structure、Terminology、Punctuation、Code examples、Formatting审计。规则是尺子流程是用法两者不可颠倒。带行号完整读取目标文件。如果用户指定的是目录或 glob则枚举所有文档逐一审计如果没给目标主动询问审计哪些文件不要擅自猜测范围。按规则类别逐条对照正文记录每个具体违规及其行号。注意这里的措辞每个具体违规every concrete violation意味着审计要落到实处不能只给泛泛的观感。按既定格式写报告建议必须具体给出真正的改写文本而不是建议修改一下give the actual rewrite, not consider revising。停下并呈现报告然后提出可以代为修复只有被明确要求时才动手改文件。这套流程与默认只报告的边界互相咬合第 5 步的offer to apply fixes; apply only if asked与 SKILL.md 第 8 行的Only modify files if the user explicitly says to fix, rewrite, or apply完全一致。12 项优先级检查清单审计不是漫无目的地通读而是按优先级扫描。audit-process.md 第 13 到 27 行给出了检查清单并注明排在最前面的条目对语音破坏最大The top items most damage the voice含糊与填充词Hedging filler如 it might be the case thatin order tobasicallysimplyjust。处理方式删掉或让它变得明确Cut or commit。被动语态Passive voice主动语态更清晰时改用主动。the function is invoked by the client → the client invokes the function.营销浮夸词 / 模糊加强词Marketing fluff / vague intensifiersseamlesslypowerfulrobustblazing-fastcutting-edgeworld-class。替换为具体表述或直接删除。Em-dash逐条标记所有 em-dash风格指南明令禁止。建议用句号、逗号、冒号或括号替换。这是硬规则连审计文档自身都必须遵守。第三人称疏离Third-person distance本应说you的地方用了the useronedevelopers can。无上下文的术语Jargon without context首现的缩写或行话没有给出 grounding首次出现时的解释性铺垫。术语不一致Inconsistent terminology同一概念被两种方式命名或核心名词App、Function、Image、Volume、Secret大小写不一致。标题大小写漂移Title-case drift单篇文档内标题在 sentence case 和 title case 之间来回切换。缺失反引号Missing backticks代码标识符、命令、参数、路径、文件名裸奔在正文里。被埋没的警告Buried warnings坑点、版本说明、受限功能说明藏在正文段落里本应做成 callout。薄弱的开头Weak openings页面或小节没有在开头点出概念或收益先清嗓子再进入正题。碎片化 / 不可运行的代码Fragment / unrunnable code片段无法直接粘贴运行或缺少预期输出 / 踩坑说明。从源码结构看这份清单的顺序本身就是设计前四项填充词、被动语态、浮夸词、em-dash直接决定读者对文档的语音观感属于最优先打击对象第 9、10、12 项关乎可操作性与信息传达效率第 11 项关乎结构。审计时可以按这个顺序逐类过一遍先解决伤筋动骨的再处理一致性打磨。报告格式可执行的 findings 而非模糊建议audit-process.md 第 30 到 56 行规定了报告的完整结构。每个 finding 遵循统一形状- file.md:42 · [Punctuation] Em-dash banned Offending: Modal is fast — really fast — and it scales automatically. Rewrite: Modal is fast, really fast, and it scales automatically.整份报告的结构为### Audit:file or scope审计范围标题Summary一行统计N findings: X high, Y medium, Z low.加一句对整体语音契合度的一行评价。High破坏语音 / 读者清晰度path:line· [Category]rule· Offending: … · Rewrite: …Medium一致性与打磨path:line· [Category]rule· Offending: … · Rewrite: …Low细节问题path:line· [Category]rule· Offending: … · Rewrite: …Patterns值得全局修复的反复出现的问题例如 the user used 11x, switch to you throughout.这个格式的设计意图很明确每条 finding 都必须可定位file:line、可复现引用确切违规原文、可执行给出目标语感下的真实改写。Summary 行给出严重度分布Patterns 段把零散发现汇总成可一次性的全局修复建议。审计规则红线audit-process.md 第 58 到 65 行划定了审计行为本身的纪律必须引用file:line让每条发现都可执行使用 Read 时的实际行号。引用确切的违规文本Quote the exact offending text不要通过转述把问题转没了。每条发现都要给出目标语感下的真实改写而不是泛泛的建议。把每条发现映射到风格指南类别Voice、Structure、Terminology、Punctuation、Code、Formatting用方括号标注。不要编造违规Dont invent violations。如果文字已经符合语感就直说一份短报告就是好结果A short report is a good outcome。默认不改文件。先报告再提出可以应用修改只有被明确要求时才写入文件。最后两条特别值得注意它们把审计与挑刺区分开来。一份合规的文档应当得到一份很短的报告这恰恰说明审计成功而不是报告越长越好。仓库级工程保障这个 Skill 自身如何被校验作为一套管文档的文档good-docs-audit本身也处在仓库的校验体系之内这体现了 Composio 对 Agent Skill 的工程化态度。Skill 结构与格式约束.agents/skills/skill-maintenance/references/skill-format.md 规定了每个 Skill 目录必须包含带 YAML frontmatter 的SKILL.mdname必须与目录名一致只用小写字母、数字和连字符详细示例和命令配方放在第一级references/*.md中SKILL.md 保持简短。这与 good-docs-audit 的布局完全吻合SKILL.md只有 17 行核心流程全部下沉到 references/audit-process.md。静态校验脚本ts/scripts/validate-agent-skills.mjs 是执行pnpm validate:agent-skills的校验器它对包括good-docs-audit在内的 18 个规范 Skill 做了硬性检查taxonomy 门禁第 13 到 32 行磁盘上的.agents/skills目录集合必须与expectedSkills列表完全一致增删 Skill 意味着同时修改三处校验列表、AGENTS.md 路由、GOAL.md 分类。frontmatter 校验第 70 到 101 行必须有 YAML frontmatter只允许name和description两个键name必须匹配目录名且符合^[a-z0-9-]$description不超过 1024 字符且必须包含触发词 Use。SKILL.md 长度约束第 152 到 155 行超过 80 行直接报错从机制上强制SKILL.md 保持简短细节进 references。references 约束第 157 到 185 行必须有 references 目录、目录内只能是第一级 markdown 文件且每个 reference 都必须在 SKILL.md 中被显式链接防止引用文件失联。兼容性镜像第 189 到 202 行.claude/skills必须是指向../.agents/skills的符号链接不允许维护平行的手工副本。命令真实性第 299 到 421 行扫描所有 Skill 文档中的pnpm、bun run、make、nox -s命令逐一比对根package.json、docspackage.json、python/Makefile和python/noxfile.py中的真实定义防止文档里出现不存在的命令。路由冒烟测试ts/scripts/test-skill-routing.mjs 是pnpm validate:skill-routing的实现它不为每个任务跑 LLM而是用一个确定性评分来守护路由稳定性。每个 Skill 必须至少有一个 probe探针其中 good-docs-audit 的探针是task: review a README for voice and tone violations and report suggested rewrites expect: good-docs-audit terms: [report violations, critique, suggested rewrite, rule violated]脚本将探针的触发短语与每个 Skill 的description做子串匹配计分断言预期 Skill 是唯一最高分第 150 到 184 行。这套机制的意图见文件头注释是捕捉最常见的回归某个 description 改版后丢掉了让它被唯一命中的关键词或另一个 Skill 的 description 产生了歧义重叠。这保证了review 文档语感这类请求永远能稳定路由到good-docs-audit。在你的文档工作流中使用这套审计这套 Skill 的价值不限于 Composio 仓库内部。你可以把它的方法论直接迁移到自己的文档工作流中作为一份文档发布前的语感自检清单先定尺子确立一份风格指南可以借鉴 style-guide.md 的六类框架Voice、Structure、Terminology、Punctuation、Code、Formatting并让它成为唯一的评分标准。按优先级扫描从破坏性最大的四项开始填充词、被动语态、浮夸词、em-dash再到一致性问题术语、标题大小写、反引号最后是可操作性被埋没的警告、薄弱开头、不可运行的代码。以可执行的格式汇报每条发现都带上file:line、原文引用、所属类别和建议改写并按 High / Medium / Low 分组末尾用 Patterns 汇总可全局修复的问题。默认只报告审计与修改解耦报告先呈现修改必须得到明确授权。用工程手段保护规则本身像 validate-agent-skills.mjs 那样把文档必须遵守的格式也变成可自动校验的断言让漂移在 CI 阶段就被拦截。一句话总结good-docs-audit教会我们的是文档质量不是靠感觉而是靠一把明确的尺子、一套有序的检查流程和一种可执行的汇报格式。审计的最高境界是当报告短到几乎无事可报时说明文档已经稳稳站在那把尺子上了。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考