SuperAPI AI 工具集

documentation

写作与研究

查看项目

更新于 10-15 21:52

技能介绍

用途:为 gh-aw 项目编写简洁、结构清晰的文档。文档位于 docs/ 目录,使用 GitHub 风格 Markdown,由 Astro Starlight 渲染,并遵循 Diátaxis 框架。

主要能力与结构:按四种 Diátaxis 类型组织内容。教程面向学习,从用户将构建的成果讲起,给出从开始到结束的步骤、具体示例与可运行代码,假设读者几乎无前置知识,只走顺利路径,用祈使语气,不深入讲概念或排错。操作指南面向目标,标题形如“How to [具体目标]”,假设读者懂基础,聚焦解决单一问题,必要时才给多种方案,达成目标即结束。参考面向信息,按结构(CLI 命令、配置项、API 端点)组织,完整权威、格式一致,列出全部参数、选项与返回值,用描述性语气,少叙述。解释面向理解,讨论设计取舍、背景与概念联系,帮助建立心智模型,用陈述语气,不写步骤或穷尽参考。

风格与语法:语气中立、技术化、不推销;避免“we/our/us”,改用“the tool”“this command”。标题用 Markdown 标题语法而非加粗。少用长列表,优先结构化散文。代码示例最小且聚焦,除非相关否则省略可选字段。智能体工作流片段用 aw 语言标签并带 YAML frontmatter。每个页面必须有 frontmatter(title、description)。可用 GitHub 警报语法(NOTE、TIP、WARNING、CAUTION、IMPORTANT)。代码块用语言标签,可用 title 属性标注文件名,aw 代码块可加 wrap。内部链接用相对路径,链接文字要有描述性。可用 Starlight 的 Tabs/TabItem 展示替代方案,用 Card/CardGrid 做导航或突出选项,但组件应尽量少用,优先标准 Markdown。

应避免:写“Key Features”章节、营销语言、过多项目符号、包含全部可选参数的冗长示例、混合文档类型。

去冗余:常见冗余包括重复内容、过长列表、重复示例、啰嗦描述、重复的“What it does / Why it's valuable”结构。编辑时应合并列表为散文或表格、删除重复信息、精简措辞、统一结构、简化代码示例。示例:把“What it does / Why it's valuable / How to use / When to use / Benefits / Learn more”式条目压缩为一句描述加使用场景与链接。

质量要求:保留原意,做精准小改而非重写,保持中立技术语气,本地验证链接与格式。按文件类型组织:入门用教程格式,操作指南一任务一篇,CLI 参考用参考格式,概念用解释格式,API 参考用参考格式。

限制:资料未提供该技能的具体安装命令、收费、平台支持或效果数据。