SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场technical-documentation

technical-documentation

写作与研究

查看项目

更新于 10-15 17:07

技能介绍

用途

该技能用于产出、审查和审计清晰、无歧义、可维护的技术文档，面向人类读者和智能体。覆盖范围包括产品文档、贡献者治理文件以及智能体指令文件。正文遵循简化技术英语（Simplified Technical English，ASD-STE100），使读者或智能体不会误读。审计通过分片、对抗性检查和并行修复，可扩展到包含数百页的文档树。

适用场景

  • 在现有产品/代码库中创建或大修文档（棕地场景）。
  • 构建旨在长期保持准确和可复用的常青文档。
  • 审查文档差异（diff）的结构、清晰度和操作正确性。
  • 跨治理文件和产品文档面（docs/、README*、.md/.mdx/.mdc、Fern/Sphinx/Mintlify/MkDocs 源）运行全仓库文档审计。
  • 审计庞大或混乱的文档树：数百页、单页超过 2 万字符、导航混乱、多语言、读者体验差。
  • 将密集或含糊的英文改写为简化技术英语：过程、参考页、错误消息、工具描述、AGENTS.md 和 CONTRIBUTING.md。
  • 更新或审查 AGENTS.md 和/或 CONTRIBUTING.md，使智能体和贡献者工作流与当前仓库实践保持一致。
  • 为带有别名指令文件（CLAUDE.md、AGENT.md、.cursorrules、.cursor/rules/*、.agent/、.agents/、.pi/）的仓库设计治理文档策略。
  • 诊断智能体文件漂移，即团队不得不反复提示才能发现缺失文件、损坏命令或策略冲突。

证据与产物

  • 常规的范围审查和审计发现保留在聊天或标准输出中。默认不创建报告文件、台账或分片目录。
  • 仅在请求的交付物或具体的大型审计、恢复或交接需求时，才创建持久证据。写入文件前说明其使用者和用途。
  • 对所需证据复用同一个任务专属位置。当大型或可恢复工作流需要时，保留覆盖、去重、日志和恢复契约。
  • 无论发现保留在行内还是文件中，都要报告覆盖范围和缺口。持久化更少绝不意味着调查更少。

工作流

  1. 将任务分类为构建、审查、审计或重写，将上下文分类为棕地或常青。
  2. 尽早清点请求的文件、目录或差异范围。文档级工作要包含治理和产品文档。仅仓库大小不会扩大范围审查。
  3. 检测多语言范围并定义所需的对等程度。
  4. 阅读 references/agent-and-contributing.md 了解智能体指令和 CONTRIBUTING.md 规则。
  5. 阅读 references/principles.md 了解治理规则集（Matt Palmer、OpenAI 和 ASD-STE100）。
  6. 在编写或重写任何正文前阅读 references/simplified-technical-english.md。按文件选择严格或 STE 风格模式。
  7. 当委派有帮助且存在 Agent 工具时使用子智能体辅助，否则使用单智能体。当范围需要分片或用户请求工作流时阅读 references/workflows.md。仅在用户选择加入且工作流工具可用时使用工作流。
  8. 构建任务遵循 references/build.md。
  9. 审查任务遵循 references/review.md 并主动检测问题。
  10. 当请求的审计范围需要分片时，遵循 references/large-docs-audit.md。先运行第 0 轮机械扫描和仓库原生验证器，然后按字符预算分片，完整审计范围内每一页。按分片批量进行对抗性检查。运行更多轮次直到两轮没有新增内容，并报告每轮新增数量，而不是声称收敛。绝不为了适应消息长度而缩短审计。
  11. 重写任务先运行 scripts/ste-lint.py，按 STE 流程重写，再重新运行 lint。硬违规不得增加。除非用户要求规则表，否则只返回重写后的文本。
  12. 大规模修复时，在编辑任何内容前用 references/pr-program.md 将台账分组为 PR，然后按阶段顺序落地。
  13. 当平台/工具选择影响建议时使用 references/tooling.md。
  14. 在请求范围内运行主动问题扫描。除非要求仅报告模式，否则在同一轮修复高置信度缺陷。
  15. 棕地模式优先兼容当前文档信息架构、工具和发布状态。常青模式优先使用永恒措辞和持久结构。
  16. 返回交付物以及验证说明、覆盖范围、对等状态和剩余缺口。

子智能体编排指南

当请求的工作范围广时优先委派。对全仓库、多框架或高冲突工作默认使用委派。

  • inventory-agent -> agents/inventory-agent.md (haiku)：文件/配置发现、覆盖图、缺失路径检查。
  • ste-lint-agent -> agents/ste-lint-agent.md (haiku)：每个分片的确定性 STE lint 基线。
  • governance-agent -> agents/governance-agent.md (sonnet)：AGENTS/CONTRIBUTING/别名优先级、冲突、策略漂移。
  • docs-framework-agent -> agents/docs-framework-agent.md (sonnet)：框架配置、相对路径基、文件路径与 URL 路径映射。
  • verify-agent -> agents/verify-agent.md (sonnet)：对单个发现进行对抗性反驳。
  • docs-ux-audit-agent -> agents/docs-ux-audit-agent.md (fable)：对单个分片进行全读读者体验审计，输出台账。
  • ste-rewrite-agent -> agents/ste-rewrite-agent.md (fable)：保持含义的严格或 STE 风格重写。
  • remediation-agent -> agents/remediation-agent.md (fable)：将已验证发现应用于单个文件，重新运行验证器。
  • synthesis-agent -> agents/synthesis-agent.md (fable)：将输出合并为一份按优先级排序的修复计划。

使用 Claude Workflows（references/workflows.md）时，审计模板对每个分片运行 docs-ux-audit-agent，并对每个分片运行一个批量 verify-agent，然后进行综合和完整性批评。逐发现验证器扇出是这些运行耗尽会话的主要方式，因此保持验证批量化和范围限定。修复模板对每个文件运行 remediation-agent，并在其后设置审查者。仅在用户选择加入后启动工作流。

输入

  • 文档类型（教程、操作指南、参考、解释）和受众。
  • 文件范围、目录范围或差异范围。
  • 文档框架/工具约束（Fern、Mintlify、Sphinx、MkDocs 等）。
  • 任务模式（构建、审查、审计、重写）和棕地/常青意图。
  • 每个文件的 STE 模式（严格或风格化），或让技能从文档类型推断。
  • 目标智能体和人类兼容意图。
  • 期望的调查深度（快速通过、详尽）。审计在请求范围内默认详尽。
  • 执行层级（工作流、子智能体辅助、单智能体）和工作流选择加入。
  • 修复模式（默认应用修复，或仅报告）。
  • 持久证据用途和路径，仅在证据与产物要求下需要时。当需要大型审计台账时，使用审计根目录下的 .audit/ledger.jsonl。
  • 多语言范围：真源语言、目标语言环境、对等期望。

输出

  • 更新后的草稿、重写文本或带有明确后续操作的审查发现。
  • 验证说明（检查了什么、还剩什么），包括 STE lint 前后计数。
  • 审计的覆盖声明：按目录列出已读页数占范围内页数。
  • 带状态计数的发现（open、verified、refuted、fixed、wontfix），默认行内或放在所需台账中。
  • 超大页面的拆分计划和导航/信息架构变更列表。
  • 触及 AGENTS/CONTRIBUTING 时的治理文档对齐摘要。
  • 智能体指令面映射（主文件、别名文件、Codex/Claude/Cursor 处理计划）。
  • 请求范围内的文档面覆盖图（/docs、README 层级、框架源树）。
  • 委派说明：使用的智能体或工作流运行 ID、委派范围、发现如何合并。
  • 逐轮发现计数和收敛声明。
  • 当任务是规模化修复时的 PR 计划。
  • 多语言对等说明（同步、部分并附理由，或有意分歧）。

流程

stateDiagram-v2 [] --> ScopeInventoryAndRules ScopeInventoryAndRules --> SelectMode state SelectMode <<choice>> SelectMode --> Build: build SelectMode --> Review: review SelectMode --> RewriteWithLint: rewrite SelectMode --> AuditScope: audit AuditScope --> InlineAudit: scoped work needs no sharding AuditScope --> ShardedAudit: scope requires coverage ledger and shards Build --> ValidateAndReport Review --> ValidateAndReport RewriteWithLint --> ValidateAndReport InlineAudit --> ValidateAndReport ShardedAudit --> ValidateAndReport ValidateAndReport --> [] note right of ShardedAudit Workflow tool use requires opt-in. Retain evidence only for a declared need. end note

限制

  • 工作流工具的使用需要用户选择加入。
  • 仅在声明需求时保留证据。
  • 关于收费、价格、平台支持范围等具体信息，资料暂未提供。