核心用法
write-a-skill 是用于创建新Agent技能的规范框架，核心流程为三阶段：需求收集 → 技能草拟 → 用户评审。技能包采用固定目录结构：SKILL.md（必需主指令）、REFERENCE.md（详细文档）、EXAMPLES.md（示例）、scripts/（工具脚本）。
SKILL.md 模板关键要素：
- Frontmatter：name/version/description（description 限制1024字符，必须包含触发条件"Use when..."）
- 三级渐进披露：Quick start（最小可用示例）→ Workflows（分步流程+检查清单）→ Advanced features（外链引用）
显著优点
1. 渐进式信息披露：避免认知过载，新手可快速上手，专家能深入高级功能
2. 触发条件显性化：description中的"Use when"机制让Agent能精准匹配用户请求
3. 资源捆绑标准化：脚本与文档的分离原则明确（确定性操作放脚本，避免重复生成代码）
4. 可维护性强：100行限制、单层引用、无时效敏感信息等约束提升长期稳定性
潜在局限
- 创作门槛：需理解Agent决策机制（description是唯一可见线索），对纯业务用户有学习曲线
- 灵活性约束：固定目录结构和行数限制可能不适配超复杂领域
- 无自动化验证：Review Checklist依赖人工执行，无内置lint工具
- 版本202.0.8：文档提及未详述的版本演进策略
适合人群
- Agent平台开发者、AI应用架构师
- 需将内部Know-how封装为可复用技能的技术团队
- 追求技能生态一致性的组织级用户
常规风险
- 描述歧义风险：description写得太泛会导致Agent误触发或漏触发
- 文件膨胀风险：未及时拆分会导致单文件超100行，破坏可读性
- 脚本安全：未明确脚本的执行权限沙箱机制（需平台层补充）
- 依赖隐式契约：Agent对"Use when"的解析逻辑未标准化，跨平台可能行为不一致