技能本质与触发机制的核心作用

AI Agent的“技能”（Skills）是将程序性知识赋予模型的最简单方式，旨在弥补大语言模型在特定工作流上的不足。尽管格式极其简化——通常只是一个包含Markdown的文件夹，甚至可能涉及运行用户机器上的随机软件代码——但其背后隐藏着将概率模型与脆弱多步任务绑定的风险。目前存在一个由 agent skills dot I O 定义的标准，但在创建技能时仍需谨慎考虑其执行逻辑。其中最关键的第一步是确保描述能够准确触发技能的运行，因为Agent的描述决定了技能是否会被实际调用。在启动阶段，由于上下文窗口限制，模型无法一次性加载所有已安装技能的完整内容，仅能读取每个技能的文件名和简短描述。因此，名称和描述必须包含足够的信息，使Agent能独立判断何时使用。例如，“生成合规报告”这一描述过于模糊，而更优的写法应明确说明：“从内部数据生成月度合规报告，当有人询问合规报告或月度申报时使用”。鉴于模型倾向于低触发（under trigger），即容易跳过本应使用的技能，描述应当适度“强势”，宁可过度推销也不宜保守。

基于真实专家知识构建内容主体

一旦技能被触发，其内部内容的质量便成为关键。许多初学者倾向于让LLM直接生成技能内容，但这往往导致产出物充满通用的废话（generic mush），如“适当处理错误”或“验证输入”，这些是模型早已知晓的基础常识，无法体现特定工作的独特性。技能的核心价值在于提供模型无法自行获取的、特定的工作方式。为了构建高质量的内容，创作者应采取两种路径：一是亲自手动执行任务并记录实际有效的步骤及修正过程；二是从现有工件（如旧报告、运行手册、代码审查意见或PR反馈）中综合提炼。正如Simon Willison所言：“保留领域专业知识，让Agent处理常规部分”。这意味着创作者需贡献核心 expertise（专家知识），而模型负责执行打字等例行工作。在技能文档的主体部分，最具价值的部分是记录“陷阱”（gotchas），即那些违背合理假设的环境特定事实。每一次手动纠正Agent的行为都应被记录下来，形成文档中的修正指南，从而避免在未来重复相同的错误。即使基于真实报告构建技能，初期仍可能出现如“行总计与总和不符”这类可捕获的错误，这证明了技能主体需要变得详尽且彻底。

上下文资源的明智分配与渐进式披露

尽管技能内容需要详尽，但长度增加会带来高昂的Token成本。当Agent选择并读取技能主体时，这些内容会进入共享上下文窗口，与所有其他信息竞争模型的注意力。因此，写作原则是“向左对齐”（write left），即只写Agent自身不知道的信息。模型已经具备关于PDF、数据库迁移等通用知识的基础，创作者无需重复这些常识。建议将技能.md的主体部分控制在500行文本以内（约五千Token）。若内容超出此限制，不应强行压缩导致信息丢失，而应利用技能文件夹中的 references 子目录进行拆分。这是一种称为“渐进式披露”（progressive disclosure）的模式，即仅在需要时才向Agent展示额外的参考文件。通过这种方式，既保留了处理复杂任务所需的深度知识，又避免了上下文窗口的浪费和成本的激增。

避免猜测：引入确定性脚本的必要性

在构建AI Agent技能时，并非所有步骤都适合让模型自行发挥。虽然对于路径多样的松散指令，模型的即兴创作通常能得出正确结果，但对于必须每次完全一致的关键步骤，依赖模型在运行时重新生成逻辑是极其危险的。这种不确定性会导致结果在不同运行中产生偏差，破坏系统的可靠性。最佳实践的核心在于根据步骤的脆弱性来调整指令的强制性：对于容错率高的松散步骤，编写自然语言指令即可；而对于一旦出错就不可接受的脆弱步骤，则应直接编写代码。这种区分对待的方法能显著降低因模型“猜测”而引发的错误。

实施细节：脚本目录与意图明确化

具体而言，开发者应将确定性代码放置在技能文件夹中的 scripts 目录下。这与引用文件（references）的管理逻辑相似，但关键在于脚本本身不会被加载到模型的上下文窗口中。这一设计不仅节省了宝贵的Token资源，还因为代码执行比模型推理更具确定性而提高了可靠性。然而，仅仅放置脚本是不够的，开发者必须在技能主体中明确指示Agent执行该脚本或将其作为参考材料。如果意图表达模糊，模型可能会将脚本误读为普通文本而非可执行指令。这一机制不仅适用于Anthropic的Claude Code，也广泛兼容如OpenAI Codex等其他主流Agent平台。通过这种方式，我们将原本概率性的模型决策转化为确定性的代码执行。

案例解析：合规报告中的数学逻辑重构

以作者构建的“合规报告”技能为例，该任务涉及行数据的求和与对账。在早期版本中，模型需要自行计算这些数字，这导致了频繁的数学错误。改进后的方案是将所有涉及加法的逻辑封装为一个确定性的数学脚本。当Agent需要执行求和操作时，它不再尝试在上下文中进行概率性计算，而是直接调用该脚本。这一改变彻底消除了此类数学Bug。正如作者所言：“答案不是写更多的测试，你可以用测试建立信任。但对于必须正确的部分，要把猜测从循环中移除。” 这种转变标志着技能开发思路的重大调整：通过硬编码确定性逻辑，取代模型在多次运行中可能不一致的概率性决策。对于开发者自己构建并经过强化的技能，这种确定性是建立信任的基础。

安全审计：第三方技能的潜在风险与应对

然而，并非所有技能都由开发者亲自构建。当使用来自陌生开发者的第三方技能时，安全风险急剧上升。由于技能文件夹可以包含可执行脚本，这些脚本有权访问本地文件系统或开发者机器上存储的API密钥。这种强大的能力正是技能生态系统的核心优势，但也带来了巨大的安全隐患。数据显示，今年早些时候的一项审计扫描了近4,000个公开技能，发现超过35%的技能存在某种安全漏洞，其中13%涉及严重问题，如提示注入或直接的恶意软件。因此，我们必须像对待任何外部代码依赖一样对待Agent技能：在使用前仔细阅读其功能并检查其网络请求。尽管技能是开放标准，但这并不意味着每个具体实现都是安全的。最佳实践第五条明确指出：在运行任何技能之前，必须进行严格的审查（Vet a skill before you run it）。

总结：构建可信赖技能的五大支柱

综上所述，一个高质量且值得信赖的AI Agent技能应遵循以下五个核心原则：首先，Agent必须能够实际触发该技能；其次，技能的构建应基于真实的实践经验而非理论假设；第三，保持技能精简以避免填满上下文窗口；第四，在涉及关键逻辑时使用确定性脚本以消除猜测带来的不一致性；最后，也是至关重要的一点，是在运行前对技能进行严格的安全审查。随着AI Agent生态系统的快速发展和更多平台采用这一开放标准，这些最佳实践可能会不断扩展。开发者应积极参与社区讨论，分享那些经过验证的有效经验（当然，前提是这些经验不包含恶意代码）。

结论

构建高可靠AI Agent技能的核心在于平衡概率模型的灵活性与确定性逻辑的稳定性。通过精准描述确保触发、基于真实专家经验提炼特定工作流，并利用渐进式披露控制上下文成本，可显著提升技能质量。关键突破在于将易错的数学或逻辑步骤封装为确定性脚本，彻底消除模型猜测带来的不一致性。然而，技能生态存在显著安全隐患，审计显示超35%公开技能含漏洞，其中13%涉及严重风险。因此，开发者必须严格审查第三方脚本权限与行为，在享受技能便利的同时建立信任基石。