如何构建“能听懂人话”的复杂技能？拆解 write-a-skill 的渐进式结构

在尝试为 AI 开发自定义技能（Skills）时，大多数开发者都会掉进同一个坑：试图写一个极其复杂的 Prompt，涵盖所有可能的边界情况。结果就是 AI 变得反应迟钝，或者在执行中途迷路。真正的“大师级”技能开发，不应该是写长篇大论的指令，而应该是构建一套具备**渐进式披露（Progressive Disclosure）**能力的逻辑框架。

Matt Pocock 的 skills 项目中内置了一个非常有趣的元技能——write-a-skill。它不仅是用来创建新技能的工具，更是一套关于“如何教 AI 学习新规矩”的架构指南。

💡 报错现象总结：开发者在编写自定义 Skill 时，常因 Prompt 逻辑耦合度过高，导致 AI 无法准确执行多步任务。常见的报错包括资源路径引用失效（Resource Not Found）或技能元数据（Metadata）定义不规范，导致 npx skills add 时无法正确解析目录结构。

告别“屎山 Prompt”：为什么你需要渐进式披露？

如果你直接给 AI 一堆杂乱无章的指令，它在处理复杂逻辑（如：先分析源码，再生成文档，最后调用 API）时会显得力不从心。

write-a-skill 提倡的架构逻辑是分层执行。它通过 bundled resources（捆绑资源）将复杂的 Prompt 拆解为多个小的、可复用的模块。

// 一个标准 Skill 的目录结构（由 write-a-skill 自动生成）
my-new-skill/
├── prompt.md        # 核心指令逻辑
├── metadata.json    # 技能定义与依赖项
├── resources/       # 辅助上下文（如：代码模板、参考范式）
└── schema.json      # 输入输出的结构化约束

这种结构的精妙之处在于：AI 只有在需要用到特定资源时，才会去“加载”它。这极大地减轻了 AI 的上下文负担，使其能够专注于当前的原子任务。

深度剖析：write-a-skill 的资源捆绑与分发机制

在 skills 的源码中，一个技能被视为一个独立的微服务单元。

组成部分	官方设计意图	实际工程收益
Progressive Disclosure	只有当用户触发特定逻辑分支时，才披露后续指令	节省 Token，防止 AI 被过载信息干扰
Bundled Resources	将最佳实践（Best Practices）打包在技能内	确保 AI 生成的结果符合预设的工程质量规范
Atomic Commands	将技能拆分为多个子命令	便于进行单元测试和逻辑排错

当你执行 npx skills@latest add .../write-a-skill 时，它会引导你通过一系列交互式提问，自动生成符合这套架构的脚手架代码。

手动复刻“工程级技能”的各种坑

如果你尝试脱离这套框架，手动去编写和部署一个复杂的 Agent Skill，你通常会遇到以下难题：

1. 路径地狱：你的 Prompt 引用了本地的某个模板文件，但在 AI 执行时，它无法正确找到该文件的相对路径，导致输出结果变成了一堆占位符。
2. 版本碎片化：当你修改了技能逻辑，你得手动通知团队里的每一个人去更新他们的 Prompt 文件。没有像 npx skills add 这种中心化的分发机制，技能同步简直是灾难。
3. 缺乏类型约束：没有 schema.json 的约束，AI 输出的 JSON 格式可能千奇百怪，导致你后续的自动化脚本（如自动提 Issue）频繁解析失败。

这种“手工作坊式”的技能开发，很难支撑起企业级的 AI 辅助流转。

让你的 AI 技能实现“工业化生产”

不要再用文本编辑器一行行磨 Prompt 了。你需要的是一套成熟的工程模板，让你的 AI 技能从出厂那一刻起就具备极高的鲁棒性。

为了帮你彻底掌握这套“技能开发艺术”，我已经在 GitCode 发布了 《Agent Skills：write-a-skill 架构解析与自定义模板包》。这份资料详细拆解了如何利用 progressive disclosure 构建能够处理复杂业务逻辑的技能，并附带了几个现成的工业级 Skill 源码供你参考。访问 GitCode，注册开发者账号，领取这套技能开发模板，开始构建你自己的 AI 武器库。

[注册 GitCode 即可获取作者同款 Skill 开发模板，助你打造“听话”的 AI 助手。]