你给 Agent 安装了十几个 Skill写周报、处理表格、审查代码、生成合同。后来却出现怪事明明有专门的表格 SkillAgent 偏偏调用通用文档 Skill更新了一条规则老项目的输出格式突然变了你又往说明文件里塞进几页示例。问题未必出在模型身上。Skill 容易被当成高级提示词写完就算交付。但反复调用、多人维护时它更像小型软件产品要让 Agent 找得到、选得对、执行稳还要能安全升级。这五关决定它能否成为可靠资产。示例要有但要服务于判断Skill 是否包含示例答案是当文字规则仍可能产生多种理解时应该包含。假设一个 Skill 要生成客户拜访纪要。“专业、简洁”很难界定给出输入与理想输出Agent 才能区分“客户诉求”和“待确认事项”。再补一个反例不能把客户“有兴趣”写成“已确定合作”。示例应覆盖正常、边界和易错情况别堆相似成品。固定格式交给模板复杂操作交给脚本主说明只留关键示例。其余放进references/EXAMPLES.md需要时再读。Claude Platform Docs1也要避免 Agent 复制示例中的公司名、数字和措辞。因此应明确标注哪些是占位信息哪些是必须遵守的结构。好示例提供边界不替代规则。Discovery 的入口往往只有几行描述一个 Skill 写得再好Agent 没选中它也等于不存在。常见的 Agent Skills 机制采用分层加载运行环境先发现可用 Skill把名称和描述交给模型任务匹配时再读取完整的SKILL.md必要时才打开参考文件或运行脚本。扫描目录和注册方式依具体环境而定。这意味着description不是宣传语而是路由规则。不要写“强大的文档助手”要写清能力、触发场景和边界。例如“从 CSV 销售数据生成月度经营报告用户要求销售趋势、地区对比时使用不处理原始账务核算。”名称也要能区分职责sales-report比helper更有辨识度。用户可以指定 Skill日常则多靠自动匹配。上线前准备几条真实提问检查它是否被正确发现、是否误抢其他 Skill 的任务。被找到与被选对需要分别验证。Skill 变多先失控的是选择成本“按需加载”能避免把所有说明同时塞进上下文却不意味着可以无限增加 Skill。候选列表仍要占空间名称和描述高度重叠时Agent 还会面对更多相似选项。若某个平台设有候选列表预算过长的描述甚至可能被截短或省略。例如团队分别做了“生成销售周报”“制作销售汇总”“销售数据报告”三个 Skill。它们数据相同字段和口径却不同。Agent 选错一个输出看似完整实际上无法交付。应按职责整理别为每个需求新建目录。同一工作流的不同模板可以收进一个 Skill由主文件判断使用哪份参考资料权限、数据来源或风险不同再拆开。记录负责人、输入输出、依赖及停用状态定期去重。判断是否该新增 Skill有个实用问题现有 Skill 加一个明确分支是否比让 Agent 多做一次选择更清楚如果答案是肯定的先别拆。版本号要标记行为不只标记文件更新可能涉及触发描述、工具、模板、脚本和输出。因此版本应对应整个 Skill 包连同依赖与测试用例一起提交而不是只给SKILL.md编号。可以在团队内部采用类似语义化版本的约定修复错别字或不改变约定行为的错误升补丁版本新增兼容能力升次版本改变输入要求、输出结构或删除旧行为升主版本。这是维护约定并非所有 Agent Skills 实现都强制采用的标准。开放格式允许通过自定义metadata记录版本托管平台也可能另有独立的版本机制。每次发布留下变更说明、环境要求和回滚办法。生产任务尽量固定到经过验证的版本不要默认跟随最新版。否则同一请求的结果变了排查时却不知道运行了哪个版本。兼容性要靠测试不能靠一句“向后兼容”最危险的修改常常看起来很小把报告中的“客户名称”改成“客户”下游自动化却仍按旧字段解析。对人而言只是措辞变化对系统而言可能就是接口破坏。更新前列出契约调用方、输入、输出字段、工具和环境依赖。再用旧版真实任务做回归测试至少覆盖正常输入、缺失数据和边界情况。还要验证路由是否正确、工具调用是否越权、下游能否读取输出。如果必须做破坏性修改可以保留旧版供现有项目使用新版提供迁移说明短期内同时支持新旧字段等调用方完成迁移后再移除旧字段。逐步放量观察失败必要时回滚。对涉及外部写入、资金或客户数据的 Skill还应要求权限检查及关键操作确认。真正的交付是让下一次调用仍然可靠回到开头Agent 调错 Skill往往不需要再写一页“请仔细理解用户意图”。先检查候选 Skill 的职责是否重叠描述是否交代触发边界最近一次更新是否改变了输出契约。这比追加提示词更值得排查。如果今天要整理自己的 Skill 库可以从一个高频任务做起给它配一组正反示例、三条发现测试、一份版本记录再用旧任务跑一遍升级回归。能复现、能比较、能回滚才说明这个 Skill 真正具备了长期使用的条件。