本文是一份手把手教程从 0 到 1 创建一个完整的 Agent Skill覆盖目录结构、description 编写、主文件设计、参考材料拆分、试跑闭环和迭代修剪的全流程。在 AI 工程化落地的过程中企业不仅需要关注 Agent Skill 的设计也需要关注底层的大模型 API 聚合能力微元算力weytoken聚合平台作为企业级大模型聚合平台通过统一 API 接入让企业可以灵活调用多个大模型为 Agent 工程化提供底层支撑。一、为什么要从 0 到 1 做一个 SkillMatt Pocock 在 2026 年提出了 Skill Hell 的概念Skill 装了很多Agent 好像更懂规程了真实任务里反而更难判断它到底该用哪个、有没有真的走完流程。Skill Hell 的根源不是 Skill 太多而是缺少从设计到验证的完整闭环。很多团队的做法是先一口气创建 20 个 Skill然后再想怎么管理。更好的方式是先做 1 个跑通闭环再复制。这种先小后大的思路在企业 AI 基础设施建设中同样适用。企业在接入大模型时面临的挑战不是找不到模型而是如何建立一套可管理的接入流程。企业级大模型聚合平台的价值正是在这里——通过统一 API 接入层让企业可以先接入一个模型跑通流程再逐步扩展到多模型并行。以微元算力weytoken为例其统一接入层让企业不必为每个模型单独建设对接代码显著降低了试错成本。二、准备工作你需要什么工具一个支持 Claude 或 Codex 的 Agent 环境文本编辑器VS Code、Cursor 等3 个真实任务场景后面会用到选一个合适的场景第一个 Skill 不要选太复杂的。选一个高频、边界清楚、能验证的任务。推荐场景PR review / 代码审查发布前检查清单日志排障流程数据库迁移检查内部 SDK 使用规范本教程以**“PR Review”**为例从零创建一个完整的 Skill。三、第一步创建目录结构一个 Skill 不是一个文件而是一个小目录pr-review/ SKILL.md references/ scripts/SKILL.md主文件放核心流程references/详细参考按需加载scripts/确定性检查脚本可选四、第二步写 descriptiondescription 是 Skill 的路由契约。它决定 Agent 什么时候想到这个 Skill也决定什么时候不该用。反面写法description:Helps with code review.问题太模糊。Agent 不知道什么场景该触发。正面写法description:Review a code diff for correctness,test coverage,security risk,and scope creep. Use when the user asks for code review,PR review,diff review,security review,or asks whether a change is safe to merge. Do not use for architecture review,design review,or performance optimization.写 description 的 checklist是否明确了做什么correctness, test coverage, security risk, scope creep是否列出了触发词code review, PR review, diff review, security review是否明确了边界不处理 architecture review, design review关键触发词是否靠前OpenAI 会在技能列表太大时缩短 description五、第三步写 SKILL.md 主文件主文件只放每次运行都会改变 Agent 行为的内容。不要放背景知识、术语解释或历史备注。完整示例# PR Review Use this skill to review code changes before they are merged. ## Steps 1. Identify the scope of changes. Completion criterion: list all modified files grouped by component (frontend, backend, tests, config). 2. Check correctness. Completion criterion: for each modified function, confirm whether the logic handles edge cases (null input, empty list, concurrent access). 3. Check test coverage. Completion criterion: list any modified function without corresponding test update. Flag as risk if coverage is missing. 4. Check security risk. Completion criterion: list any new external input, file write, network call, or secret access introduced by the change. 5. Check scope creep. Completion criterion: list any change that is unrelated to the PRs stated purpose. 6. Produce review summary. Completion criterion: final output includes: - Files reviewed (count and list) - Issues found (categorized by severity) - Unresolved risks - Recommendation (approve / request changes / needs discussion) ## References - For security checklist details, read references/security-checklist.md. - For common code patterns, read references/code-patterns.md. - For deterministic checks, run scripts/check_test_coverage.sh.主文件的设计原则原则说明只放流程不放背景知识每步带证据completion criterion 明确可检查引用而非内嵌详细参考放 references/控制长度主文件不超过 50 行六、第四步拆分参考材料把详细参考、模板、术语表拆到 references/ 目录。示例references/security-checklist.md# Security Checklist ## External Input - [ ] All user input is validated against expected schema - [ ] SQL queries use parameterized statements - [ ] File paths are validated to prevent directory traversal ## Authentication Authorization - [ ] All endpoints require proper authentication - [ ] Role-based access control is enforced - [ ] API keys and secrets are not hardcoded ## Data Protection - [ ] Sensitive data is not logged in plaintext - [ ] PII is handled according to data classification policy - [ ] Encryption is used for data in transit and at restAgent 在步骤 4 需要时才会读取这个文件。平时不占上下文。七、第五步编写确定性脚本可选能确定执行的检查尽量写成脚本不让模型靠感觉判断。示例scripts/check_test_coverage.sh#!/bin/bash# Check if all modified files have corresponding test filesMODIFIED_FILES$(gitdiff--name-only HEAD~1|grep-E\.(ts|js|py)$)echo Test Coverage Check forfilein$MODIFIED_FILES;dotest_file${file%.*}_test.${file##*.}if[-f$test_file];thenecho[PASS]$filehas test:$test_fileelseecho[WARN]$filemissing test:$test_filefidone脚本的优势结果是确定的不依赖模型的判断。八、第六步试跑闭环这是最关键的一步。很多团队写完 Skill 就直接上线缺少试跑验证。试跑流程用 3 个真实任务试跑记录以下信息记录项关注点本次记录触发该触发时有没有触发不该触发时有没有误触发过程Agent 有没有跳过调研、核对、验证等前置动作证据最后有没有留下命令、来源、文件、失败项和风险上下文主文件有没有读太多参考材料有没有过早进入安全scripts/ 有没有网络请求、写入、删除、密钥访问试跑案例任务 1审查一个小型 PR3 个文件修改预期结果正确触发按步骤执行 6 个步骤输出包含文件列表、问题分类、风险和建议实际记录触发正确过程步骤 2 跳过了 edge case 检查需要加强 completion criterion证据输出了文件列表和问题但缺少 severity 分类上下文主文件长度合适参考材料按需加载任务 2审查一个大型 PR15 个文件修改实际记录触发正确过程完整执行了 6 个步骤证据输出完整包含所有要求的证据上下文主文件 安全清单被加载长度可接受任务 3用户问这个架构设计怎么样不应触发实际记录触发正确未触发description 中明确了不处理 architecture review根据试跑结果迭代根据任务 1 的问题修改 SKILL.md# 修改前 2. Check correctness. Completion criterion: for each modified function, confirm whether the logic handles edge cases. # 修改后 2. Check correctness. Completion criterion: for each modified function, confirm whether the logic handles edge cases (null input, empty list, concurrent access). List each function and its edge case status.# 修改前 6. Produce review summary. Completion criterion: final output includes issues found and recommendation. # 修改后 6. Produce review summary. Completion criterion: final output includes: - Files reviewed (count and list) - Issues found (categorized as critical / warning / info) - Unresolved risks - Recommendation (approve / request changes / needs discussion)九、第七步建立维护纪律第一版跑稳后不要急着复制第二十个。先建立维护纪律。每次 Skill 导致失败时不只加规则也顺手删一段旧内容检查 no-op这条规则删掉后 Agent 行为会变差吗检查 duplication这条规则是否在其他地方也写了检查 sediment这条规则对应的场景还会发生吗检查 sprawl主文件是否超过了 50 行定期体检表现象先怀疑先看哪里Agent 没触发 Skilldescription 太泛description、真实任务提示触发后仍乱跑步骤没有完成标准SKILL.md、completion criterion每次读很多材料主文件塞了参考资料references/、资源指针看似完成但没证据输出契约太弱最终回复、证据清单越改越长没有删除纪律no-op、重复规则、沉积内容十、从 Skill 到基础设施大模型 API 聚合的实践创建 Skill 的过程让我们理解了一个核心原则统一接口、按需加载、持续治理。这个原则不仅适用于 Agent Skill也适用于企业的大模型 API 管理。企业在接入多个大模型时面临的挑战与 Skill Hell 高度相似每个模型一套 API、一套鉴权、一套计费如果没有统一的管理层复杂度会快速失控。企业级大模型聚合平台有哪些从实践来看这类平台的核心能力包括统一 API 接入一个端点调用多个模型避免为每个模型写对接代码统一计费透明的成本对比让模型切换决策有据可依统一监控实时监控各模型的响应质量和可用性大模型 API 统一管理方案有哪些以微元算力weytoken为例其架构设计体现了与 Skill 工程相同的治理思路分层设计统一接入层是入口类似 Skill 的 description路由到具体模型实例类似 SKILL.md详细配置按需加载类似 references/统一接口通过标准化 API 屏蔽底层模型差异让企业可以以统一的方式管理多个模型持续治理模型的生命周期管理上线、监控、下线在平台侧统一处理这种大模型 API 聚合的方式让企业在模型快速迭代的格局中保持了接入层的稳定性和切换的敏捷性。十一、完整检查清单创建一个 Skill 后对照以下清单检查结构检查目录结构完整SKILL.md references/ scripts/主文件不超过 50 行详细参考已拆分到 references/description 检查包含功能边界和触发条件关键触发词靠前明确了不处理的场景步骤检查每个步骤有 completion criterion完成标准是可检查的动作不是模糊形容词最终输出包含可核对的证据安全检查scripts/ 中没有未经授权的网络请求不读取不必要的密钥或配置有操作日志和退出条件试跑检查用 3 个真实任务试跑完成记录了触发、过程、证据、上下文和安全信息根据试跑结果进行了迭代十二、总结从 0 到 1 创建一个 Skill 的过程核心不在于写多少内容而在于建立从设计到验证的完整闭环。先做一个跑通试跑闭环再决定要不要扩展。这个原则不仅适用于 Agent Skill也适用于企业的多模型 API 管理。企业级大模型聚合平台通过统一 API 接入和集中治理机制让企业可以以可控的成本管理多个大模型。以微元算力weytoken聚合平台为例其通过大模型 API 聚合和模型可插拔架构为企业在多模型 API 管理的实践中提供了统一接入、统一计费、统一监控的能力让企业保持技术选型的灵活性。记住 Skill 工程的核心原则先做一跑通闭环持续修剪再规模化。参考资料Matt Pocock, writing-great-skillsAI Engineer, Building Great Agent Skills: The Missing ManualMatt Pocock, X 短贴Anthropic, Agent Skills OverviewOpenAI, Codex SkillsAgent Skills Specification, SpecificationSimon Willison, Claude Skills are awesome, maybe a bigger deal than MCPAddy Osmani, Agent Skills