Addy Osmani的Agent技能:规范编写与前端反模式

Addy Osmani拥有89.4K星标的开源项目“agent-skills”引入了一套用于构建AI代理指令的规范。其核心是SKILL.md文件,这是每个技能唯一必需的文件,并可选包含scripts/和references/目录。关键设计规则包括:前置描述需回答“做什么”和“何时做”,但不总结过程以防止走捷径;“常见合理化”部分预先列出AI跳过步骤的借口;“验证”部分要求基于证据的退出标准。脚本必须将JSON输出到标准输出。该项目有意做出权衡,将共享引用存储在根目录以维护单一事实来源,牺牲了每个技能的可移植性。概述了六项写作原则:过程优于知识、具体性、证据优于假设、反合理化、渐进式信息揭示和令牌意识。配套分析识别出AI生成界面中常见的八种前端UI反模式:默认紫色/靛蓝色、过度渐变、统一大圆角、模板化英雄区、占位文字、过大内边距、统一卡片网格和浓重阴影,每种模式皆因其在训练数据中的普遍性及其对设计质量和性能的负面影响而得到解释。
Key insights
AI指令必须预先阻止合理化才能有效
SKILL.md中的“常见合理化”部分是最具创新性的特性,它明确列出了AI代理可能用来跳过步骤的借口,并提供了反驳论点。这种设计承认语言模型与人类一样,会试图为走捷径寻找合理理由。通过预先阻断这些路径,该规范从假设合规转向工程化行为可靠性。该方法借鉴了人类行为工具(如检查清单和纪律表),将其直接适配到提示工程中,以实现更可预测的AI代理执行。
AI生成的前端代码存在八种可识别的视觉反模式
对AI生成的UI代码的详细分析揭示了八种反复出现的反模式:默认紫色/靛蓝色配色方案、过度渐变、统一大圆角、模板化英雄区域、占位文字、过大内边距、统一卡片网格和浓重阴影。这些模式源于它们在训练数据中的过度呈现,例如Tailwind示例和Stripe风格的落地页。负面影响包括品牌差异化丧失、用户信任受损、占位文字掩盖布局错误以及阴影渲染导致性能下降。该分析倡导基于设计系统、有意的选择,而非统计默认值。
Agent技能结构通过渐进式信息揭示强制执行令牌经济
该规范通过设计强制实行严格的令牌经济。SKILL.md被限制为500行,详细的信息被放置在脚本或单层引用文件中,按需加载。规则要求脚本将结构化数据输出到标准输出,因为脚本执行本身不消耗上下文,但内联代码块每次加载都会产生令牌成本。这种设计将提示上下文视为可计费资源,确保主技能文件中的每一段都必须通过直接促进行为改变来证明其令牌成本的合理性。
共享引用涉及可移植性与一致性之间的文档化权衡
该项目有意将共享的测试、安全和性能检查清单放置在根references/文件夹中,而不是在每个技能目录内重复。这避免了多个副本不可避免的偏差。然而,该规范公开记录了这种权衡:该方法牺牲了独立安装单个技能及其所有依赖项的能力。该权衡被记录并跟踪为第361号议题,展示了刻意记录工程债务而非忽视它的实践。