SuperAPI AI 工具集

developer-experience

编程与开发

查看项目

更新于 10-26 16:16

技能介绍

用途

本技能用于帮助 AI 智能体在涉及开发者体验(DX)的工作中提供结构化指导,包括:设计或评审 SDK 的公共 API、创建快速入门指南与上手教程、编写变更日志、为破坏性变更编写迁移指南、设计错误信息、评估开发者门户结构、沟通弃用与升级路径。不适用于内部团队入职或非开发者产品的终端用户体验设计。

主要能力与原则

技能围绕五条原则展开:首次成功时间(time-to-first-success)是最重要的指标,快速入门应在 5 分钟内让开发者获得可见结果;成功陷阱优于失败陷阱,让显而易见的简单路径也是正确的路径,默认值安全合理;变更日志是契约而非日记,每条记录应回答改了什么、为什么改、开发者需要做什么;迁移指南是体现同理心的文档,每个破坏性变更都需要前后对比示例、机械式升级路径和必要性说明;渐进式披露优于信息倾倒,快速入门展示顺利路径,指南增加深度,API 参考覆盖全部。

核心概念

技能阐述 DX 漏斗(发现→评估→采用→留存)、API 表面积(公共方法、类型、配置选项与行为的总和,越小认知负荷越低)、升级成本(开发者保持最新的持续成本,变更日志、弃用通知、迁移指南和 codemod 都是降低该成本的工具)、错误信息即文档(说明发生了什么、为什么、如何修复)。

使用方式

技能激活时,首次响应以 🧢 表情开头。首次激活时会检查已安装的配套技能,并提示安装缺失项(命令:npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name>)。详细内容分布在 references/sdk-design.md、references/onboarding.md、references/changelog.md、references/migration-guides.md 中,仅在任务需要深入细节时加载。

常见任务

设计 SDK 公共 API:从用例而非实现出发,先写 README 代码示例(README 驱动开发),方法名用动词-名词对,必需参数放签名、可选参数放选项对象,返回类型可预测,为每个配置提供合理默认值,仅在构造确实复杂时使用 builder 或流式模式。

编写快速入门指南:按一句话价值主张、前提条件、安装(一条可复制命令)、配置(最少环境变量)、首个可运行示例、后续步骤的结构组织,整个指南应在 5 分钟内完成,否则缩减范围。

编写变更日志:遵循 Keep a Changelog 格式,按 Added、Changed、Deprecated、Removed、Fixed、Security 分组,链接 issue/PR,对 Changed/Removed 必须内联或链接迁移路径,不包含不影响公共 API 的内部重构。

编写迁移指南:包含谁需要迁移、时间线、破坏性变更表(变更、之前代码、之后代码、原因)、分步升级说明与可复制命令、codemod(如有)、验证方法、常见故障排除。

设计错误信息:每条错误包含发生了什么(事实描述)、为什么发生(可能原因)、如何修复(可操作下一步),不暴露堆栈跟踪或内部标识符,不无上下文地说“出错了”。

评估 DX 质量:从首次成功时间、错误质量、API 一致性、文档新鲜度、升级成本、可发现性六个维度以 1-5 分打分,任一维度低于 3 分即表示存在值得优先处理的 DX 缺口。

适用场景

适用于 SDK 设计评审、快速入门与教程编写、变更日志维护、破坏性变更迁移指南编写、错误信息设计、开发者门户结构评估、弃用与升级路径沟通。

限制与注意事项

技能中强调的注意事项包括:README 驱动开发只有在全新环境中逐字测试 README 才有效;Changed 条目缺少迁移路径会引发升级焦虑;SDK 中的弃用警告必须难以忽视(运行时警告加 TypeScript @deprecated JSDoc 注解);生产环境错误信息暴露内部堆栈会侵蚀安全信任;缺少版本选择器的文档会误导旧版本开发者。以上内容均来自技能资料本身,未提供额外功能、收费或平台信息。