学习AI软件开发生命周期——构建Agent技能的完整指南
内容提要
Agent Skills是一种AI代理技能格式，通过SKILL.md文件让代理按需读取指令，避免重复解释。文章以deck-builder为例，展示如何构建、优化技能：包括触发描述、脚本验证、参考文件、评估测试及安全扫描。该格式支持多工具，能显著节省token，但需注意安全风险，安装前应扫描。
延伸解读
为什么渐进式披露能大幅节省Token
文章用公式对比了静态加载与渐进式披露的Token消耗：50个技能、每个5,000 Token时，静态加载需250,000 Token，而渐进式披露仅需10,000 Token，节省96%。关键在于技能按需激活，而非全部常驻上下文。但注意，激活后的技能会持续占用上下文，且对话压缩时可能被移除，因此技能设计应保持精简，避免无关文件。
技能描述是触发成败的关键
技能描述是代理决定是否激活技能的唯一依据，但常被忽视。文章强调描述应写成指令式（如“当用户要求……时使用”），覆盖用户可能使用的模糊表述（如“周四弄个东西”），并明确排除不适用场景（如编辑现有幻灯片）。通过构建正负样本测试集（约20条）并多次运行，可量化触发率，避免过度拟合。
脚本验证让流程可检查而非仅靠提示
纯文本指令无法保证代理遵循流程，而捆绑脚本（如validate_deck.py）能提供可验证的检查。脚本设计需面向代理：非交互式、输出结构化（JSON）、错误信息包含修复建议、幂等且输出受限。文章示例用Python标准库实现零依赖，确保长期可用。这使“检查工作”从建议变为可重复的机制。
跨工具兼容需遵循规范而非客户端扩展
Agent Skills格式虽被多工具支持，但客户端扩展（如Claude Code的argument-hint）可能导致严格验证失败。文章建议：若需跨工具使用，仅使用规范定义的六个字段（name、description等），并确保name与文件夹名一致。同时，技能存放位置因客户端而异，需确认目标客户端扫描的目录，否则技能可能无法被发现。
Q&A
什么是 Agent Skills？它解决什么问题？
Agent Skills 是一种 AI 代理技能格式，通过 SKILL.md 文件让代理按需读取指令，避免重复解释。它解决了每次会话都要重新向 AI 模型解释工作流程的问题，将专业知识和工作流固化在代码库中，供团队所有代理复用。
Agent Skills 如何节省 token？相比把所有指令放在系统提示词中有什么优势？
Agent Skills 采用渐进式披露，代理启动时只读取约 100 token 的元数据，仅在任务需要时才加载完整的 SKILL.md 正文（最多 5000 token）。相比将所有指令放在系统提示词中，每次请求都加载全部内容，可节省大量 token。例如，50 个技能、每个 5000 token，静态加载需 250,000 token，而渐进式加载仅需 10,000 token，节省 96%。此外，长上下文会导致指令遵循度下降，而技能文件短小精悍，指令更容易被遵循。
如何构建一个 Agent Skill？请以 deck-builder 为例说明基本步骤。
构建 Agent Skill 的基本步骤：1. 创建技能文件夹，如 deck-builder/；2. 在文件夹内创建 SKILL.md 文件，包含 YAML 前端元数据（name, description 等）和 Markdown 正文；3. 将技能文件夹放在客户端识别的目录（如 .claude/skills/）；4. 测试技能是否被发现和触发。以 deck-builder 为例，它教代理先进行头脑风暴（确定受众、核心信息、叙事弧），再写幻灯片，避免直接生成通用幻灯片。
SKILL.md 文件中的 description 字段有什么作用？如何优化它以确保技能被正确触发？
description 字段是代理在决定是否使用技能时唯一看到的部分，因此至关重要。优化原则：1. 写成指令形式，如“当用户要求……时使用此技能”；2. 描述用户意图而非技能架构；3. 覆盖用户可能使用的各种说法，包括不直接说“演示文稿”的情况；4. 注意 1024 字符限制。通过构建包含正负样本的测试集（约 20 个查询）来评估触发率，并根据失败案例调整描述，避免过度拟合。
Agent Skills 支持哪些工具？技能文件夹应放在哪里？
Agent Skills 支持超过 45 种工具，包括 Claude Code、VS Code、GitHub Copilot、Cursor、Gemini CLI、Codex、Goose、JetBrains Junie 和 Google Antigravity。技能文件夹的位置因客户端而异：Claude Code 使用 .claude/skills/（项目级）和 ~/.claude/skills/（个人级）；VS Code/Copilot 支持 .github/skills/、.claude/skills/、.agents/skills/；Antigravity 使用 .agents/skills/。.agents/skills/ 是新兴的跨客户端约定，但 Claude Code 不识别它。
如何验证 Agent Skill 的有效性？有哪些评估方法？
验证技能有效性包括：1. 使用官方验证工具 skills-ref validate 检查前端元数据和命名；2. 构建触发测试集（约 20 个正负样本查询），运行多次计算触发率，确保正样本触发率高于 0.5，负样本低于 0.5；3. 使用评估套件（evals/）测试技能的实际输出质量，例如检查生成的演示文稿是否符合要求。
安装 Agent Skill 时需要注意哪些安全风险？
安装 Agent Skill 前应进行安全扫描，因为技能可能包含恶意指令或脚本。建议使用官方或可信来源的技能，并在安装前检查 SKILL.md 内容和捆绑的脚本。文章提到“Scan Before You Install”，强调安全扫描的重要性。
