skill如何设计
设计有效的Agent Skill需要遵循简洁性、原子性、渐进式披露三大核心原则，通过三层结构化设计将技能拆分为元数据、核心流程和附加资源，确保每个技能专注单一任务且能按需加载。
以下是经过验证的设计方法与实战示例：
一、设计前的准备：明确技能边界
1. 技能审计与边界定义
- 对现有流程进行全面盘点，识别可拆分的独立任务单元
- 为每个技能问三个关键问题：
- 它解决哪个"能力缺口"？
- 这个能力出现在工作流的哪个阶段？
- 当前技能边界是否只围绕一个主线任务？
反例：将"查询客户记录"和"更新客户状态"合并为"管理数据"技能
正例：拆分为"查询客户记录"和"更新客户状态"两个独立技能
2. 自由度设置原则
- 高自由度：适用于创意任务（如内容创作），只给方向不给具体步骤
- 中自由度：适用于有推荐做法但允许变通的任务（如代码重构）
- 低自由度：适用于操作脆弱的任务（如金融计算、API调用），需严格步骤
示例：
- 前端设计技能：
Choose a BOLD aesthetic direction: brutally minimal, maximalist chaos...（高自由度）- PDF表单填写技能：
1. Run: python scripts/extract_form_fields.py input.pdf（低自由度）
二、Skill核心结构设计：三层架构
1. 最小可行结构（MVP）
my-skill/
└── SKILL.md # 核心配置与流程文档
2. 完整结构（按需扩展）
my-skill/
├── SKILL.md # 核心说明文档（必选）
├── scripts/ # 自动化脚本目录（可选）
│ ├── run.sh # 一键执行脚本
│ └── check.py # 质量校验脚本
├── templates/ # 输出模板目录（可选）
│ └── report.md # 标准化输出模板
└── references/ # 参考资源目录（可选）└── playbook.md # 操作手册、规范参考
三、SKILL.md编写规范：从元数据到核心流程
1. YAML元数据（必填）
name: "image-generator" # 64字符内，小写字母/数字/连字符
description: "根据用户需求生成图片。" # 1024字符内，明确触发场景
version: 1.0
trigger: ["生成图片", "制作海报", "设计配图"] # 触发关键词
命名规范：
✅analyzing-sales-data（动名词形式）
❌helper（过于通用）
2. 核心内容编写（Markdown正文）
极简指导型示例（写作规范Skill）：
## 指令：公众号写作规范
此技能用于确保AI生成内容符合品牌调性。**核心原则**：
1. **避免AI腔**：禁用"综上所述"、"在当今时代"等套路表达
2. **真实案例**：必须基于真实数据和行业案例
3. **结构清晰**：每段≤3句，关键点加粗**执行流程**：
1. 接收用户主题和brief
2. 检索相关行业数据和案例
3. 生成3个选题方向供确认
4. 根据确认选题撰写初稿
5. 三遍审校：事实核查→风格优化→细节打磨
工具脚本型示例（PDF表单处理Skill）：
## 指令：PDF表单处理
此技能用于提取PDF表单字段并填写表单。**工作流程**：
1. **解析输入**：确认PDF路径和输出路径
2. **提取字段**：运行`python scripts/extract_form_fields.py input.pdf`
3. **收集值**：向用户确认所有字段值
4. **填写表单**：运行`python scripts/fill_form.py input.pdf output.pdf --data fields.json`**输出规范**：
- 成功：`PDF表单已成功填写并保存至：{output_path}`
- 失败：`{"error": "字段{field_name}不存在"}`
四、设计质量保障：避免常见陷阱
1. 三大质量校验原则
- 能否减少重复Prompt？无需额外解释上下文，直接调用即可执行
- 能否保证输出一致性？有固定输出结构和校验规则
- 能否应对异常情况？针对工具故障、权限不足有明确兜底方案
2. 渐进式披露实践
- 第一层：技能目录（~100 tokens）— Agent启动时只加载name和description
- 第二层：技能说明书（<5000 tokens）— 技能触发时加载SKILL.md
- 第三层：技能资源包（按需加载）— 仅在需要时加载scripts/和references/
3. 200行规则与冷启动测试
- SKILL.md不超过200行，超出必须拆分或迁移内容
- 冷启动测试：清空会话，仅激活某一个技能，统计首次加载总行数
- 将"冷启动上下文≤500行"作为红线阈值
五、实战案例：数据分析Skill设计
需求：让AI分析用户流失数据并生成热力图
Skill设计：
name: "user-churn-analysis"
description: "分析用户流失数据，识别高流失率渠道和用户行为共性，生成热力图对比数据。"
trigger: ["分析流失率", "用户流失分析", "churn analysis"]## 指令：用户流失分析
此技能用于分析用户流失数据并生成可视化报告。**输入要求**：
- CSV文件路径（必须包含：user_id, channel, behavior_data, churn_status）
- 分析周期（默认上周）
- 对比周期（默认上月）**执行流程**：
1. **数据验证**：- 检查CSV格式和必要字段- 验证时间范围有效性2. **核心分析**：- 按渠道计算流失率并排序- 识别Top 3高流失率渠道- 分析流失用户行为共性（使用`scripts/behavior_analysis.py`）3. **可视化生成**：- 创建流失率热力图（使用`scripts/heatmap_generator.py`）- 生成对比报告（包含环比变化）**输出规范**：
- 成功：包含流失率数据表、热力图和关键发现的Markdown报告
- 失败：`{"error": "缺少必要字段：{field_name}"}`
附加文件：
scripts/behavior_analysis.py：分析用户行为模式scripts/heatmap_generator.py：生成热力图templates/report.md：标准化报告模板references/data_schema.md：数据格式说明
六、设计流程总结
- 明确场景：确定技能解决的具体业务问题
- 选择模式：根据任务复杂度选择五种结构模式之一
- 写Description：用100字内清晰描述技能功能和触发条件
- 写核心流程：按步骤说明执行逻辑，控制在200行内
- 补充资源：将详细说明、脚本、模板放入对应目录
- 测试迭代：通过冷启动测试和实际调用验证效果
关键提醒：记住你在写的是"给AI的操作手册"，不是给人看的文档。使用祈使句（"提取文本"而非"我将提取"），假设AI已具备基础能力，只补充它不知道的业务规则。
高质量的Skill设计能让AI从"偶尔惊艳"变为"稳定可靠"，真正成为团队工作流的一部分，而不是一个孤立的聊天玩具。当开始像设计系统架构那样设计Skills，你的Agent将摆脱对人工干预的依赖，实现从"信息获取"到"决策落地"的全流程自主。