Agent Skill 规范、构建与设计模式¶

Ch04.614 Agent Skill 规范、构建与设计模式¶

📊 Level ⭐⭐ | 5.8KB | entities/agent-skill-spec-building-design-patterns.md

基于 Anthropic Agent Skills 规范、Skill-Creator 方法论、Superpowers Writing-Skills 框架及 Google ADK 设计模式的系统性总结。

Skill ≠ Prompt：Skill 是围绕任务、工具、流程和输出边界的结构化行为设计，是可复用的 Prompt 增强包。

仅允许 Unicode 小写字母、数字和连字符，不能以连字符开头/结尾。

解决上下文膨胀问题的核心机制，借鉴 UI/UX 渐进式信息披露策略：

层级	内容	加载时机	Token 成本
L1 目录层	name + description	会话启动时	~50-100 tokens/个
L2 指令层	完整 SKILL.md body	Skill 被激活时	建议 <5000 tokens
L3 资源层	scripts/references/assets	指令引用时按需	视文件大小

即使安装 20 个 Skill，初始加载仅 1000-2000 tokens，上下文使用量减少约 90%。

完全由模型自行判断当前任务是否匹配 description，非关键词硬编码。

最关键发现：Description 只应描述触发条件，绝不要总结工作流程——否则 Agent 会直接按 description 执行，跳过读取完整的 SKILL.md 正文。

核心思想：像做机器学习一样做 Prompt Engineering。

模式	核心逻辑	适用场景
Tool Wrapper	SKILL.md 不写完整规范，只告诉 Agent 去 references/ 按需加载	框架/库封装、团队编码规范
Generator	模板 + 风格指南 + 主动提问	标准化文档生成、项目脚手架
Reviewer	分离"查什么"与"怎么查"，解释 WHY 不是 WHAT	自动化 PR 审查、安全扫描
Inversion	翻转交互模式：Agent 先采访用户，再动手	新项目规划、需求不明确场景
Pipeline	多步严格顺序，明确输入/输出/通过条件	多阶段内容生产

推荐组合：Pipeline + Reviewer（多阶段生成+审查）、Generator + Inversion（采访后生成）。

Vercel 发布的开放、厂商中立标准，为 Skill + MCP server 提供统一的可分发打包格式——解决同一组件在不同客户端格式下需重复适配的问题。

目录契约：plugin.json（最低要求 $schema + name）+ 固定目录结构——skills/ 放 SKILL.md（含 scripts/references）、mcp.json 放 MCP 配置、com.example.client/ 放客户端专属扩展
组件独立校验：客户端校验 manifest 后组件各自独立验证——一个组件无效不拖垮其他组件
不做重定义：Skill 与 MCP 已有各自规范，Agent Plugins 只定义"客户端如何一起发现组件"，不重新定义组件本身（commands/hooks/agents 留给客户端）
小而有意：v1 只聚焦两种组件类型（Agent Skills + MCP servers），其余由 Technical Steering Committee 后续扩展
与 SKILL.md 标准的关系：本文档 21-25 行的 Anthropic SKILL.md 格式（scripts/references/assets）与 Agent Plugins 的 skills/summarize/{SKILL.md,scripts,references} 目录结构直接兼容——打包标准复用而非替换 Skill 规范