核心用法
write-a-skill 是面向开发者与 AI 架构师的技能生成框架，用于标准化创建可复用的 Agent 能力模块。其核心价值在于将零散的业务逻辑封装为结构清晰、易于维护的技能单元。
主要流程分为三步：
1. 需求收集 — 明确任务域、具体用例、是否需要可执行脚本、参考材料
2. 草稿生成 — 输出 SKILL.md（核心指令）、REFERENCE.md（详细文档）、EXAMPLES.md（示例）、scripts/（工具脚本）
3. 用户评审 — 确认覆盖度、调整详略、优化结构
关键设计原则：
- 描述优先：SKILL.md 的 description 字段是 Agent 选技能的唯一依据，必须包含触发条件（"Use when..."），限 1024 字符
- 渐进披露：核心流程放 SKILL.md（<100 行），高级功能外链 REFERENCE.md
- 脚本隔离：确定性操作（验证、格式化）抽离为独立脚本，避免重复生成代码
- 文件拆分：内容超过 500 行或跨域时拆分，保持引用层级不超过一层
显著优点
- Agent 原生设计：从技能发现到加载的全链路优化，description 直接决定 Agent 的调度准确性
- 工程化规范：目录结构、文件命名、内容长度均有明确约束，降低团队协作成本
- 可维护性强：模块化拆分 + 外链引用，避免单文件膨胀
- 资源捆绑：支持将参考文档、示例、脚本与指令打包，实现"即插即用"
潜在局限
- 学习成本：需理解渐进披露、触发词设计等概念，对新手不够直观
- 描述 crafting 负担：1024 字符的限制与触发条件设计需要迭代优化
- 生态依赖：目前主要服务于特定 Agent 框架，通用性待验证
- 版本管理：未明确说明多版本技能共存或升级策略
适合人群
- AI Agent 开发者与平台架构师
- 需要将业务 SOP 转化为可复用 AI 能力的团队
- 追求技能标准化、可维护性的中大型项目
常规风险
| 风险类型 | 说明 |
|---------|------|
| 描述失效 | 触发词设计不当导致 Agent 无法正确加载技能 |
| 文件膨胀 | 未遵守 100/500 行限制，影响 Agent 上下文效率 |
| 版本漂移 | 多环境技能版本不一致造成行为差异 |
| 脚本安全 | 捆绑的 utility 脚本未经审计，存在执行风险 |
安全备注：提供的认证报告为系统自动占位，未执行实际安全扫描，生产环境使用前建议补充 SAST 与依赖检查。