前言
本文面向想要上手编排 AI Agent 能力的开发者、产品同学。大家搭建 Agent 时常遇到这些痛点：所有规则全部塞进 Prompt，内容臃肿、上下文超长，token 成本高且效果不稳定；分不清模型推理与代码工具的适用边界，计算容易出错；业务规范和模板混杂在一起，输出格式不稳定；缺少模块化设计，新增能力只能修改主 Prompt，难以复用；逻辑全部堆砌一处，调试困难，故障定位分不清是 Prompt、规则还是模板的问题。Skill 模块化方案，就是用来解决这些问题。
一句话理解 Skill
Skill 就是给 AI Agent 安装的能力包，也可以理解成一份独立的操作手册。
它清晰告诉 Agent：什么场景触发这个能力、执行步骤是什么、输出要长成什么样。
Skill 的组成
一个 Skill 的标准目录结构：
skill-name/
├── SKILL.md # 必需：入口指令、能力描述、执行流程
├── scripts/ # 可选：可执行脚本工具
├── references/ # 可选：业务参考知识库
└── assets/ # 可选：模板、静态素材
重点：只有 SKILL.md 是必需文件，其余三个目录按需添加，不是必须全部建好。
写 Skill 的核心规范
- 职责单一：一个 Skill 只负责一件事，不要把多个无关能力打包在一起。
- 触发清晰：明确定义什么时候启用这个Skill，避免多个Skill互相抢占触发。
- 步骤动作化：写清楚先后执行动作：先做什么，再做什么。
- 输出明确：固定输出格式，保证结果稳定。
- 尽量简短：不要把SKILL.md写成万字长文，复杂规则放到 references。
⚠️ 避坑提醒（反例）
❌ 坏例子：单个Skill同时实现写周报、生成PPT、发送邮件。触发条件混乱，后续维护难度极高。
✅ 好做法：拆分成周报Skill、PPT生成Skill、邮件发送Skill，独立管理。
SKILL.md 怎么写？
文件分为两部分：
示例：
—
name: weekly-report
description: 根据用户提供的工作内容生成统一格式的周报。当用户说“写周报”时触发。
—
# 目标
生成一份简洁规范的周报。
# 步骤
1. 收集输入信息：本周完成事项、下周计划、风险。
2. 按照固定规范组装内容。
3. 校验必填项是否完整。
# 输出格式
## 本周完成
## 下周计划
## 风险
权衡原则：简短的业务规则直接写在 SKILL.md；篇幅长、需要经常变更的规范，单独放到 references。
