前言

随着 Claude Code、Cursor、GitHub Copilot 等AI编程工具广泛普及，Skill作为可复用、可迭代、工程化的AI能力包，成为提升AI编程协作效率的核心载体。多数开发者容易混淆Skill与临时Prompt，写出的技能存在触发不准、执行混乱、稳定性差、难以维护等问题。本文结合行业最佳实战，从基础概念辨析、标准化目录与语法规范、核心设计原则、自由度分级设计、评测驱动开发流程、多场景实战案例、开发避坑注意事项、高频报错排错方案多个维度，系统拆解AI Agent Skill完整编写体系，附带可直接复用的生产级模板与上线自查清单，适配个人开发提效、团队规范统一、工程化落地迭代等各类场景。

一、基础认知：搞懂 Skill 核心定义与边界

1.1 什么是 Skill

Skill 是面向 AI Agent 的结构化可工程化指令包，以标准化文件封装固定工作流程、校验规则、参考资料与辅助脚本，是支持长期复用、版本迭代、团队共享的AI能力模块。其核心价值是解决临时Prompt随机性强、稳定性差、无法沉淀维护的痛点，通过标准化约束，保障AI执行任务的稳定性、一致性、可维护性，相当于为AI Agent配备一套标准化、可落地、可迭代的专属工作手册，实现一次编写、全局复用、持续优化。

1.2 核心概念区分（易混淆概念对比）

多数开发者极易混淆 Skill、临时 Prompt、全局 Rule、MCP 协议四类AI能力载体，导致开发适配出错、场景使用混乱。下表从核心定位、生命周期、加载逻辑、内容形态、适用场景五大维度，清晰区分四者差异，彻底厘清使用边界：

对比维度	临时 Prompt	Skill（技能包）	Rule（全局规则）	MCP（模型上下文协议）
核心定位	单次即兴指令	按需触发的独立能力	全局强制约束	标准化工具调用协议
生命周期	用完即弃，无留存	长期生效，支持版本迭代	永久全局生效	工具层通用接口
加载方式	实时输入	语义匹配触发后加载	全程常驻上下文	AI 主动调用服务
内容形态	纯自然语言指令	元数据 + 步骤 + 脚本 + 参考文档	基础规范、安全红线	接口定义、鉴权配置
典型场景	临时提问、即兴调试	代码审查、接口生成、数据处理	编码规范、安全禁令	调用数据库、浏览器、Git 等外部工具

核心边界总结：Rule 是全场景强制遵守的底线规范，Skill 是专属场景的独立工作能力，临时Prompt是单次即兴交互，MCP是打通外部工具的标准化协议，四者各司其职、互补协同，共同构建工程化AI Agent能力体系。

1.3 主流支持平台

目前主流 AI 编程 Agent 均全面兼容 Anthropic 官方 Skill 规范（该规范已于2025年12月开放为跨平台开源标准，由 agentskills.io 维护），核心平台包含：Claude Code、Cursor、GitHub Copilot、Windsurf 等。各平台核心编写语法、加载逻辑、设计规范基本统一，仅 Skill 本地存放目录略有差异，本文所有案例可跨平台通用。

需特别注意的跨平台/跨场景差异（以 Claude 官方产品为例）：

• 自定义Skill不会跨Surface自动同步：上传到 claude.ai 的自定义Skill不会自动出现在 API 中，反之亦然；Claude Code 的Skill基于文件系统，与前两者完全独立，需要分别管理、分别上传；

• Claude Code 仅支持自定义Skill：不像 claude.ai 和 Claude API，Claude Code 不提供 pptx/xlsx/docx/pdf 等预置Skill，需开发者自行编写或安装；

• 共享范围不同：claude.ai 上的自定义Skill仅归属个人，团队成员需各自上传，不支持管理员统一分发；Claude API 中自定义Skill为workspace级共享，团队成员均可调用；Claude Code 中Skill可放置于个人目录（~/.claude/skills/）或项目目录（.claude/skills/），也可通过 Claude Code Plugin 形式共享。

1.4 三大层级渐进式加载机制

为严控Token消耗、杜绝上下文臃肿、保障触发与执行效率，官方定义了三级渐进式加载机制，这是Skill开发必须遵守的底层核心逻辑，所有标准化技能均基于该机制设计：

• L1 元数据层（常驻上下文）：仅包含 name 和 description，官方规定 name ≤64字符、description ≤1024字符，是 AI 语义检索、判断技能是否触发的唯一依据，全程常驻上下文、零冗余占用，单个Skill平均仅占约100 token；

• L2 主体层（触发后加载）：SKILL.md 核心规则正文，仅当L1元数据匹配成功后才会加载进入上下文，官方建议控制在5000 Token以内（并非强制行数限制，行数仅作工程经验参考），保证执行高效；

• L3 资源层（按需懒加载）：scripts 脚本、references 规范文档、assets 资源模板等附属文件，默认不加载，仅AI执行过程中主动调用时按需读取，极致节省Token资源。

三级加载机制实现了「轻量常驻、按需加载、资源隔离」的最优平衡，既保证AI快速语义匹配触发技能，又能最大化节省上下文资源，是生产级Skill与普通自定义Prompt的核心区别之一。

二、标准目录结构与文件规范

2.1 完整目录体系

根据业务复杂度、使用场景，Skill目录分为极简单文件结构（新手/轻量场景）与工程化多目录结构（团队/复杂生产场景），开发者可按需选用，兼顾便捷性与规范性：

极简结构（单文件，适合简单任务）

仅保留核心文件，适合单一、轻量化场景：

simple-skill/
└── SKILL.md  # 唯一核心文件（文件名必须全大写）

工程结构（全目录，适合复杂团队场景）

支持脚本、参考文档、模板拆分，适配企业级复用与迭代：

full-skill/
├── SKILL.md          # 主文件（YAML元数据+执行指令，必选）
├── scripts/          # 可执行脚本（可选，存放自动化命令、校验脚本）
│   └── check-rule.sh
├── references/       # 参考文档（可选，存放规范、长文档、背景知识）
│   └── standard.md
└── assets/           # 资源模板（可选，存放配置、格式模板、ASCII图表）
    └── template.json

路径补充：

• 全局 Skill（本机所有项目生效）：Claude Code 放置于 ~/.claude/skills/，Cursor 放置于 ~/.cursor/skills/；

• 项目级 Skill（仅当前项目生效）：统一放置在项目根目录 .claude/skills 或 .cursor/skills，随项目Git版本管理、团队共享。

2.2 核心文件 SKILL.md 语法规范

SKILL.md 是技能唯一核心文件，由顶部YAML元数据和主体Markdown规则正文两部分组成。元数据决定技能识别与触发，正文定义执行逻辑，任意格式、语法错误都会直接导致技能加载失败、触发异常、执行失效，需严格遵循标准化规范编写。

2.2.1 YAML 元数据（头部，必写）

位于文件最顶部，以 --- 包裹，定义 Skill 标识、触发规则等核心属性，关键字段规范如下：

字段	是否必填	格式要求	作用说明
name	是	小写字母+数字+连字符（kebab-case）、≤64字符，必须与文件夹名完全一致，禁止包含XML标签，禁止使用保留词"anthropic"、“claude”	Skill唯一身份标识，用于系统识别、手动指令调用
description	是	第三人称陈述句、≤1024字符、禁止包含XML标签、无歧义，包含「功能+触发场景+禁用场景」	语义匹配核心，直接决定技能触发准确率
user-invocable	可选（部分平台扩展字段，非Anthropic官方标准字段）	true / false	是否支持手动命令唤起（/指令调用）
priority	可选（部分平台扩展字段，非Anthropic官方标准字段）	0-100 整数	技能优先级，数值越高越优先触发，解决多技能冲突
version	可选（部分平台扩展字段，非Anthropic官方标准字段）	自定义语义化版本号	用于技能迭代、版本回溯、团队同步
allowed-tools	可选（Anthropic官方实验性字段，后续可能调整）	枚举官方工具名（Read、Bash、Write等）	最小权限管控，限制AI可调用的系统工具

说明：根据Anthropic官方文档，YAML元数据中唯一明确定义且稳定的必填字段是 name 与 description；allowed-tools 为官方标注的实验性（experimental）字段；user-invocable、priority、version 目前未见于Anthropic官方规范，是部分编辑器/平台（如Cursor等）在实践中扩展出的字段，跨平台使用前建议先确认目标平台是否支持解析。

元数据示例

---
name: code-review-java
description: 对Java代码进行规范审查、安全检测与性能分析。适用于代码提测、PR审核场景；仅处理Java文件，不负责前端、配置文件审查。
user-invocable: true
priority: 85
version: 1.1
allowed-tools: Read, Bash
---

2.2.2 Markdown 正文（主体，执行规则）

正文无强制语法，但建议采用标准化模块划分，保证逻辑清晰、AI 易理解。通用标准模块：

1. 适用 / 禁用场景：明确什么时候用、什么时候绝对不用（规避误触发）；

2. 前置条件：执行前需要检查的环境、文件、依赖；

3. 分步执行流程：指令式步骤，拒绝模糊描述；

4. 输入 / 输出规范：结构化定义入参、出参格式；

5. 检查点 / 验证规则：每步完成后的自检逻辑；

6. 失败处理策略：异常场景的应对方案；

7. 补充参考：关联文档、脚本调用指引；

8. 避坑提示（Gotchas）：AI 易出错的边界场景。

三、Skill 核心设计原则与自由度分级

3.1 五大黄金设计标准（评审核心依据）

五大黄金设计标准是行业通用的Skill开发、评审、上线核心依据，所有生产级技能必须完全契合，是区分玩具级技能与工程化技能的核心标准：

1. 边界明确：清晰定义正向触发条件与反向禁用条件，杜绝模棱两可，从源头减少漏触发、误触发；

2. 输入输出结构化：参照函数签名思维，明确定义入参、出参格式，保证交互标准化；

3. 步骤可执行：全部使用祈使句指令，描述具体动作，拒绝概括性、主观化语言；

4. 失败策略完备：预判各类异常（文件缺失、命令报错、格式错误），定义对应的处理逻辑；

5. 职责单一：一个 Skill 只负责一项核心任务，禁止功能堆砌，复杂流程拆分为主 Skill + 子 Skill 组合。

3.2 自由度分级设计（按需选择约束强度）

基于任务容错率、标准化要求、自主发挥空间，可将Skill分为低、中、高三档自由度，不同业务场景匹配对应约束强度，避免约束过死适配性差、约束过松输出混乱的问题：

1. 低自由度（强约束）

   • 适用场景：操作固定、容错率极低的任务（数据库迁移、脚本执行、配置修改）；

   • 设计方式：直接提供可执行脚本、固定步骤，AI 仅负责按顺序执行，无自主决策空间。

2. 中自由度（平衡约束）

   • 适用场景：有固定框架、允许少量变通（报告生成、文档编写、代码模板填充）；

   • 设计方式：提供模板 / 框架，AI 在固定结构内补充内容。

3. 高自由度（弱约束）

   • 适用场景：创意类、分析类任务（方案评估、代码思路分析、文案创作）；

   • 设计方式：仅提供原则与启发式策略，依靠上下文自主判断与发挥。

3.3 通用反模式（坚决规避）

以下为Skill开发高频反模式，也是新手最容易踩的设计误区，会直接导致技能失效、逻辑混乱、无法维护，开发过程中必须坚决规避：

1. 大杂烩设计：一个 Skill 捆绑多个无关任务，步骤臃肿、AI 识别混乱；

2. 描述模糊：description 使用内部黑话、语义宽泛，无法精准匹配；

3. 纯文字描述：复杂流程不搭配示例、脚本、表格，易造成AI理解偏差；

4. 硬编码静态信息：写入时效性内容、固定路径、密钥，后期无法维护；

5. 缺少检查点：流程一次性执行到底，出错后难以定位问题；

6. 跨平台路径不兼容：使用 Windows 反斜杠路径，在 Linux/macOS 环境报错。

四、全流程开发：评测驱动 + 失败优先迭代法

专业团队摒弃「写完即用」的粗放开发模式，统一采用评测驱动、失败优先的六步闭环开发流程，从根源上提升Skill稳定性、准确率与容错性，适配生产级落地迭代：

Step 1 建立基线（无 Skill 测试）

不启用任何 Skill，直接让 AI 执行目标任务，记录不稳定输出、理解偏差、遗漏步骤等问题。这些问题就是 Skill 需要解决的核心痛点。

Step 2 定义评测用例（失败优先）

优先梳理负面用例 + 边界用例，再补充正常用例。明确每个用例的 “通过 / 失败” 判定标准，提前划定红线。

Step 3 编写最小化 Skill

基于基线问题，编写最简版本，仅保留核心流程与失败拦截逻辑，不做功能拓展，保证最短成功路径可用。

Step 4 补充边界与结构化规则

在最小版本基础上，逐步补充边缘场景、输入输出格式、参考文档，完善整体能力。

Step 5 回归评测迭代

使用所有评测用例复测，新增规则必须对应新用例，未通过则简化 Skill，禁止盲目叠加内容。

Step 6 线上校准

正式投入使用后，持续收集误触发、执行异常案例，反向更新规则，形成长期迭代闭环。

五、实战模板：多场景可直接复用

本章汇总多组覆盖低、中、高自由度的生产级实战案例，涵盖新手入门、日常运维、后端开发、测试提效等高频场景，所有案例均适配Cursor、Claude Code平台，源码可直接复制部署、上线使用。

5.1 案例一：Java 代码审查 Skill（中自由度，团队通用）

目录结构

java-code-review/
├── SKILL.md
├── scripts/
│   └── security-check.sh  # 安全检测脚本
└── references/
    └── java-coding-standard.md  # 编码规范

配套参考模板（references/java-coding-standard.md 示例）

# Java 编码通用规范

1. 类名采用大驼峰，方法名、变量名采用小驼峰；
2. 常量全部大写，单词间用下划线分隔；
3. 所有方法必须添加功能注释，核心逻辑行添加行内注释；
4. 禁止在代码中硬编码密钥、接口地址等敏感信息。

SKILL.md 完整内容

---
name: java-code-review
description: 审查Java业务代码的编码规范、安全漏洞、性能隐患与异常处理。触发场景：代码提测、PR合并前检查、代码优化重构；仅处理.java后缀文件，不处理前端、配置、纯注释文件。
user-invocable: true
priority: 88
version: 1.0
allowed-tools: Read, Bash
---
# Java代码审查 Skill
## 一、适用与禁用场景
✅ 使用场景：Java业务类、工具类、接口Controller类代码审查
❌ 禁用场景：非Java文件、纯注释修改、静态配置文件、第三方源码
## 二、前置检查

1. 校验目标文件后缀为 `.java`，非Java文件直接终止执行；
2. 优先执行 `scripts/security-check.sh` 完成安全预扫描；
3. 读取 references 目录下Java编码规范，作为审查基准。
## 三、分步审查流程

1. 编码规范审查：校验类名、方法名、常量命名、代码缩进、注释规范；
2. 安全漏洞检测：排查硬编码密钥、SQL注入、XSS攻击、未校验入参等高危问题；
3. 业务逻辑校验：检查空指针风险、异常捕获范围、事务一致性、参数合法性；
4. 性能优化分析：排查循环嵌套、资源未释放、集合冗余、重复计算等问题。
## 四、标准化输出格式
### 代码审查结构化报告

1. 🔴 严重高危问题（故障/安全风险）：精准标注位置+问题描述+修复方案
2. 🟡 中危优化建议（性能/可维护性）：问题说明+最优优化方向
3. 🟢 低危规范提醒（编码风格）：标准化调整建议
### 总结：整体风险等级 + 整改优先级 + 核心问题汇总
## 五、执行检查点
每完成一项审查步骤，自主校验结果准确性；发现高危安全问题时，优先标注并终止非必要检查，聚焦核心风险。
## 六、异常失败处理

1. 文件不存在/非Java文件：输出明确提示，终止执行；
2. 安全脚本执行报错：提示扫描异常，转为人工代码审查；
3. 代码无有效问题：输出「代码合规，无安全及规范问题」。
## 七、参考规范
详细编码标准、安全规则参考：references/java-coding-standard.md
## ⚠️ Gotchas 核心避坑点

1. 仅输出审查报告，**禁止直接自动修改生产代码**；
2. 严格区分测试代码与生产代码，差异化适配审查标准；
3. 必查资源释放、空指针、事务回滚等生产高频BUG场景。

部署&验证用例

1. 部署路径：项目级 .cursor/skills/java-code-review/ 或 .claude/skills/java-code-review/，重启工具；

2. 验证指令：上传一段Java代码，执行指令「执行代码审查」。

5.2 案例二：代码单元测试生成（低自由度，强约束）

---
name: go-unit-test
description: 为Go语言函数自动生成标准化表驱动单元测试。用户请求编写单测、补充测试用例、完善单元测试覆盖率时触发，仅适配Go语言代码。
user-invocable: true
priority: 90
---
# Go单元测试生成规则
## 一、适用与禁用场景
✅ 适用：Go语言业务函数、工具函数、接口方法单元测试生成
❌ 禁用：非Go代码、第三方框架源码、main入口函数（无测试意义）
## 二、前置要求

1. 基于用户提供的完整Go函数源码生成测试用例；
2. 仅使用官方标准testing库，不引入任何第三方测试依赖；
3. 遵循Go原生表驱动测试编码规范。
## 三、强制执行步骤

1. 解析目标函数入参、出参、核心业务逻辑、返回值规则；
2. 全覆盖设计三类用例：正常场景、边界极值场景、异常错误场景；
3. 采用标准表驱动模式编写代码，使用t.Run实现子测试隔离；
4. 自动补充测试运行命令、覆盖率统计指令。
## 四、标准化输出模板（见下方独立代码示例）
## 五、失败处理

1. 无Go函数源码：提示「请提供需要生成单测的Go函数完整代码」；
2. 函数逻辑复杂：优先覆盖核心场景，标注未覆盖分支，提示人工补充。
## ⚠️ Gotchas

1. 严格贴合Go原生编码规范，不生成冗余、不兼容代码；
2. 优先覆盖空值、极值、异常参数，提升测试覆盖率；
3. 测试代码与业务代码逻辑严格对齐，不篡改业务规则。

标准化输出模板（表驱动测试示例）

func TestXXX(t *testing.T) {
        tests := []struct{
                name    string
                入参类型  变量类型
                want    预期返回值
        }{
                // 正常业务用例
                {"正常场景：常规参数调用", 入参值, 预期结果},
                // 边界极值用例
                {"边界场景：临界参数调用", 边界参数, 预期结果},
                // 异常错误用例
                {"异常场景：非法参数调用", 错误参数, 预期报错/空值},
        }
        for _, tt := range tests {
                t.Run(tt.name, func(t *testing.T) {
                        if got := 目标函数(入参); got != tt.want {
                                t.Errorf("函数执行结果不匹配，期望：%v，实际：%v", tt.want, got)
                        }
                })
        }
}

验证用例：粘贴Go工具函数，指令「为这个函数生成单元测试」。

5.3 案例三：文档格式化（高自由度）

---
name: doc-format
description: 对技术文档进行排版、分段、层级优化。用户要求整理文档、格式化笔记时触发。
priority: 70
---
# 技术文档格式化规则
## 适用场景
纯文本、Markdown技术文档梳理与美化。
## 核心原则（高自由度，自主发挥）

1. 按照「大标题→二级标题→正文→列表」划分层级；
2. 长段落拆分，重点内容加粗标记；
3. 代码片段单独包裹代码块；
4. 保持原有核心内容，不篡改原文语义。
## 禁用规则
不新增原创内容，仅做格式优化。

验证用例：粘贴一段杂乱文本，指令「格式化这份技术文档」。

5.4 实战案例一：简易随机值生成 Skill（高自由度·新手入门）

适用场景：开发测试生成随机数字、随机字符串、测试验证码、模拟参数，轻量化高频工具，无复杂脚本，纯规则驱动。
核心能力：接收用户自定义范围、位数需求，自动生成合规随机值，适配单元测试、接口调试场景。

目录结构（极简单文件）

random-generate/
└── SKILL.md

完整 SKILL.md 源码

---
name: random-generate
description: 开发测试专用随机值生成技能，用户需要随机数字、随机字符串、测试验证码、模拟参数时自动触发，支持自定义数值范围、字符位数，仅用于开发调试，不用于生产密钥生成。
user-invocable: true
priority: 75
version: 1.0
---
# 随机值生成 Skill
## 一、适用与禁用场景
✅ 适用：开发调试、单元测试、接口模拟、测试数据生成
❌ 禁用：生产环境密钥、密码、核心隐私数据生成
## 二、前置条件
无需外部文件、脚本依赖，纯规则化执行。
## 三、分步执行流程

1. 解析用户需求：确认需要生成「随机数字」或「随机字符串」，提取范围、位数参数；
2. 无参数时默认规则：数字默认 1-100，字符串默认6位大小写字母+数字组合；
3. 按照用户自定义参数精准生成对应随机值；
4. 格式化输出结果，标注生成规则与适用场景。
## 四、输入输出规范
- 输入：自然语言指令（如：生成8位随机字符串、生成1-1000随机整数）
- 输出：清晰展示生成结果 + 生成规则说明
## 五、失败处理策略

1. 参数非法（负数、特殊字符）：提示「参数不合法，请输入正整数有效范围」；
2. 需求模糊无参数：按默认规则生成并主动告知默认配置；
## ⚠️ Gotchas 避坑要点

1. 严禁生成高强度密钥、生产密码，仅用于测试场景；
2. 不重复生成完全一致结果，保证测试数据随机性；
3. 严格区分纯数字、纯字母、混合字符三种生成模式。

上线核验步骤

放置于项目级 .cursor/skills/random-generate/（Cursor）或 .claude/skills/random-generate/（Claude Code），重启技能加载，输入指令即可测试。
验证用例

1. 生成6位随机测试字符串

2. 生成1-500的随机整数

3. 生成-10~10的随机数字（校验非法参数拦截）

5.5 实战案例二：项目日志清洗 Skill（中自由度·日常运维）

适用场景：开发调试、线上问题排查、日志梳理，自动过滤无效日志、去重、归类报错、提炼异常信息，解决日志杂乱、难以定位问题的痛点。
核心能力：自动过滤空行、重复日志、普通INFO日志，聚焦ERROR、WARN异常信息，结构化输出问题清单与排查建议。

目录结构（工程化轻量结构）

log-clean/
├── SKILL.md
└── references/
    └── log-filter-rule.md  # 日志过滤规则参考

配套参考模板（references/log-filter-rule.md 示例）

# 日志过滤通用规则

1. 过滤所有纯心跳检测 INFO 日志；
2. 过滤重复打印的普通请求日志；
3. 保留全部 ERROR、WARN、Exception 相关日志堆栈；
4. 屏蔽日志内手机号、身份证、密钥等敏感字段。

完整 SKILL.md 源码

---
name: log-clean
description: 开发日志清洗与异常分析技能，用户上传日志文件、粘贴日志内容、需要排查报错日志时触发，自动过滤无效信息、归类异常、输出结构化排查报告，适配Java、Go、前端项目日志。
user-invocable: true
priority: 82
version: 1.0
allowed-tools: Read
---
# 日志清洗与异常分析 Skill
## 一、适用与禁用场景
✅ 适用：开发调试日志、服务运行日志、接口报错日志、测试日志梳理
❌ 禁用：加密日志、二进制日志、生产敏感隐私日志解析
## 二、前置条件

1. 接收用户粘贴的日志文本或本地.log日志文件；
2. 优先读取 references 目录下过滤规则，无规则则使用默认通用规则。
## 三、分步执行流程

1. 日志预处理：过滤空行、空格行、重复日志、普通INFO冗余日志；
2. 异常筛选：精准提取 ERROR、WARN、Exception、报错堆栈信息；
3. 分类整理：按「连接异常、参数异常、空指针、超时异常、未知报错」归类；
4. 问题分析：匹配常见开发报错原因，给出针对性排查方向；
5. 结构化输出清洗报告与优化建议。
## 四、输出格式规范
### 日志清洗分析报告

1. 日志概览：原始日志行数、有效异常行数、冗余过滤行数
2. 🔴 严重异常（需优先修复）：报错位置+报错信息+根因分析+修复建议
3. 🟡 警告信息（优化项）：问题描述+优化方向
4. ✅ 正常日志（已过滤冗余）
## 五、检查点

1. 清洗完成后核对异常信息无遗漏、无错删；
2. 无异常日志时主动提示「当前日志无有效报错，服务运行正常」。
## 六、失败处理策略

1. 日志内容为空：提示「未检测到有效日志内容，请重新上传或粘贴」；
2. 日志格式混乱：尽可能识别有效报错，同时提示「日志格式不规范，部分内容无法解析」。
## ⚠️ Gotchas 避坑要点

1. 不泄露、不解析日志中的手机号、密码、密钥等敏感信息；
2. 保留完整报错堆栈，不截断关键异常链路；
3. 区分测试环境与生产环境报错，差异化给出建议。

验证用例：粘贴混杂INFO、ERROR的日志，指令「清洗并分析日志」。

5.6 实战案例三：接口参数校验 Skill（低自由度·强约束·生产级）

适用场景：后端接口开发、代码提测、CRUD接口参数校验，标准化校验规则，统一参数判空、长度、格式、合法性校验，杜绝参数校验遗漏问题。
核心能力：强制遵循后端开发参数校验规范，自动检查接口入参完整性、合法性、安全性，输出校验报告与标准化修复代码。

目录结构

api-param-check/
└── SKILL.md

完整 SKILL.md 源码

---
name: api-param-check
description: 后端接口参数校验技能，用户开发接口、检查入参、优化接口代码、提测前自查时触发，强制校验参数判空、长度、格式、非法字符、安全风险，输出标准化校验报告与修复代码。
user-invocable: true
priority: 90
version: 1.0
---
# 后端接口参数校验 Skill
## 一、适用与禁用场景
✅ 适用：Java/Go/Python 后端RESTful接口、CRUD接口、新增/修改/查询接口参数校验
❌ 禁用：前端页面参数、静态配置参数、第三方封装底层接口
## 二、前置条件
获取完整接口代码、Controller方法、入参实体类代码
## 三、强制校验步骤（固定流程，不可省略）

1. **非空校验**：必填参数校验空字符串、null、空集合，禁止参数空值直接入库；
2. **长度校验**：字符串参数校验最大/最小长度，防止超长数据入库报错；
3. **格式校验**：手机号、邮箱、身份证、账号等特殊参数正则格式校验；
4. **范围校验**：数字参数校验正负值、区间范围，杜绝非法数值；
5. **安全校验**：排查SQL注入特殊字符、XSS非法字符、敏感参数；
6. **业务校验**：校验参数是否符合当前接口业务逻辑，避免参数滥用。
## 四、输出规范

1. 列出所有缺失的校验逻辑；
2. 标注风险等级（高危/中危/低危）；
3. 给出可直接复制的校验代码片段；
4. 总结接口参数整体合规性。
## 五、失败处理策略

1. 无接口代码：提示「请提供对应接口Controller代码与入参实体类」；
2. 代码解析异常：提示「代码格式异常，无法完整校验，请核对代码」；
3. 无校验问题：输出「当前接口参数校验完整，符合开发规范」。
## ⚠️ Gotchas 避坑要点

1. 禁止跳过必填参数非空校验，这是生产高危漏洞；
2. 禁止忽略特殊字符校验，规避注入攻击风险；
3. 校验代码必须贴合项目技术栈，不生成不兼容代码；
4. 新增参数必须配套新增校验规则，杜绝参数遗漏校验。

验证用例：粘贴后端接口代码，执行指令「检查接口参数合法性」。

案例通用部署&排错总结

1. 部署规范：所有自定义Skill统一存放项目级 .cursor/skills/自定义文件夹名（Cursor）或 .claude/skills/自定义文件夹名（Claude Code），文件夹名严格匹配yaml中name字段，全小写kebab-case命名；

2. 触发失效排查：优先检查description是否精准、priority优先级是否过低、是否存在场景冲突；

3. 执行异常排查：低自由度Skill重点核对步骤完整性，高自由度Skill重点优化描述精准度；

4. 迭代建议：可基于以上基础案例，按需拓展脚本工具、自定义规则，适配个人/团队专属开发规范。

六、AI Agent Skill 开发核心注意事项（实战必看）

结合官方规范与大量一线落地实战，本章系统性总结Skill全流程开发核心注意事项，覆盖命名规范、语法编写、逻辑设计、性能优化、安全合规、调试迭代、团队协作七大维度，精准规避90%以上的技能加载失败、误触发、执行异常、无法迭代等问题，适配个人提效与团队工程化落地。

6.1 命名与目录规范注意事项

命名和目录是Skill正常加载、精准触发的基础，也是最容易出错的环节，必须严格遵守：

• 严格统一命名：Skill 文件夹名称必须和 YAML 中 name 字段完全一致，全程采用小写 kebab-case 命名（小写字母+数字+连字符），禁止大写、驼峰、中文、特殊符号，否则Skill直接加载失败。

• 文件名固定不变：核心主文件必须命名为 SKILL.md，全大写格式，禁止修改大小写、自定义文件名，AI工具仅识别标准命名文件。

• 目录层级精简：禁止多层嵌套冗余目录，简易场景单文件部署，复杂场景仅保留scripts、references、assets三个可选目录，避免层级过深导致工具读取失败。

• 路径适配跨平台：绝对禁止使用Windows反斜杠路径、本地绝对固定路径、带中文的路径，统一使用Linux标准正斜杠相对路径，适配Windows、macOS、Linux全平台。

6.2 YAML元数据编写注意事项

元数据是Skill的「识别入口」，直接决定触发准确率，微小错误就会导致功能失效：

• Description必填且精准：描述必须同时包含核心功能、触发场景、禁用场景，语言简洁无歧义，不使用行业黑话、模糊词汇，字数控制在1024字符以内，禁止包含XML标签，保障AI语义精准匹配。

• name字段同样有硬性约束：仅允许小写字母、数字、连字符，长度≤64字符，禁止包含XML标签，禁止使用"anthropic"、"claude"等保留词，否则会导致加载失败。

• 优先级合理配置：核心业务Skill（代码校验、代码审查）优先级设置80-95，工具类Skill（随机生成、文档格式化）设置60-75，避免多Skill场景下优先级冲突、错误触发（注：priority字段为部分平台的扩展实现，并非Anthropic官方标准字段，使用前需确认目标平台是否支持）。

• 工具权限按需开启：严格通过 allowed-tools 限制AI可调用工具，最小权限原则，无需Bash、文件读取权限的轻量化Skill禁止开放权限，规避误操作风险（注：该字段为Anthropic官方标注的实验性字段，具体行为以官方文档实时更新为准）。

• 禁止冗余字段：不随意新增官方未定义的YAML字段，不重复配置相同参数，避免解析报错、Skill加载异常。

6.3 业务逻辑与规则设计注意事项

规则设计决定Skill执行稳定性，是区分“玩具Skill”和“生产级Skill”的核心：

• 严格遵循单一职责：一个Skill只负责一类核心任务，禁止功能堆砌，不要将代码审查、文档格式化、单测生成等无关功能整合在一个Skill中，避免AI执行逻辑混乱。

• 步骤必须可落地执行：所有操作步骤使用祈使句、指令式描述，拒绝模糊、概括性语句，每一步都有明确动作，无主观判断空间，保证每次执行结果一致。

• 必须完善异常兜底：所有Skill都要配置失败处理策略，覆盖文件不存在、参数非法、代码解析异常、脚本执行报错、空内容输入等边界场景，避免执行中断、无输出、报错崩溃。

• 区分自由度合理设计：固定流程、强规范场景用低自由度约束，创意分析场景用高自由度引导，杜绝约束过死无法适配业务，或约束过松输出混乱的问题。

6.4 性能与Token优化注意事项

不合理的Skill设计会导致上下文臃肿、Token消耗过高、响应变慢：

• 严格遵循三级加载机制：精简L1元数据内容，name控制在64字符内、description控制在1024字符内，保证常驻上下文轻量化；L2主体内容官方建议控制在5000 Token以内；大型参考文档、脚本统一放入L3资源目录，仅按需加载，不常驻占用Token。

• 禁止冗余内容堆砌：正文不堆砌无效科普、重复规则、冗余案例，只保留执行必需的逻辑和规范，精简无效文本，提升AI识别和执行效率。

• 定期清理废弃内容：迭代过程中及时删除失效规则、废弃脚本、过期参考文档，避免内容冗余导致匹配延迟、触发异常。

6.5 安全与合规开发注意事项

Skill面向项目全局生效，必须规避安全风险，杜绝生产隐患：

• 禁止硬编码敏感信息：严禁在Skill文件、脚本、注释中写入密钥、密码、令牌、本地隐私路径、个人信息等敏感数据。

• 规避高危操作：Skill脚本和规则中，禁止配置强制删除、格式化磁盘、批量清空数据、高危权限授权等危险操作，避免误操作导致项目数据丢失。

• 屏蔽隐私数据解析：日志解析、代码扫描类Skill，需自动屏蔽手机号、身份证、密钥、隐私日志内容，禁止解析和输出用户敏感信息。

• 区分测试与生产场景：所有Skill默认适配开发测试环境，禁止自动适配生产高危操作，生产级能力需手动开启权限、增加二次确认机制。

• 审慎使用第三方/不可信来源的Skill：根据Anthropic官方安全建议，Skill本身可以是攻击载体——恶意Skill可以在SKILL.md正文或捆绑脚本中夹带指令，诱导AI执行非预期的工具调用、访问不可信外部网络地址，甚至窃取敏感数据。安装非自建、非Anthropic官方发布的Skill前，应像安装第三方软件一样，完整审查SKILL.md正文、脚本、图片等所有捆绑文件，重点排查是否存在与Skill声明功能不符的网络请求、文件操作。

• 注意数据保留政策差异：Agent Skills功能目前不在Anthropic的Zero Data Retention（ZDR，零数据保留）覆盖范围内，Skill的定义内容与执行数据会按标准数据保留策略留存。对数据合规要求严格的企业场景，需提前确认这一点是否符合内部数据治理要求。

• 留意不同运行环境的网络权限差异：Claude API中运行的Skill默认无网络访问权限、且无法运行时安装新依赖包，仅能使用预置依赖；Claude Code中运行的Skill则拥有与本机程序等同的完整网络访问权限；claude.ai中的网络权限取决于用户/管理员设置，可能是完全、部分或无网络访问。涉及联网调用的脚本设计，必须先确认目标运行环境的网络权限，避免部署后无法联网导致功能失效。

6.6 调试与迭代注意事项

• 先最小可用，再迭代优化：初次开发优先实现核心能力，保障基础流程可用，再逐步补充边界场景、优化规则，禁止一步到位堆砌复杂逻辑，导致难以调试排错。

• 正负用例全覆盖测试：上线前不仅测试正常场景，重点测试边界用例、错误用例，验证不触发、错触发、执行异常等问题，保证Skill稳定性。

• 版本规范迭代：小优化、Bug修复更新小版本，架构重构、能力大升级更新大版本，版本迭代同步更新元数据，做好版本记录，方便团队回溯。

• 及时处理冲突Skill：多个Skill存在场景重叠时，通过调整优先级、细化禁用场景规避冲突，避免互相干扰、随机触发。

6.7 团队协作适配注意事项

• 统一团队规范：团队共用Skill统一目录、命名、格式、输出规范，禁止个人随意自定义格式，保证团队协作一致性。

• 纳入版本管理：所有自定义Skill纳入Git管理，新增、修改、删除均走评审流程，禁止本地私有Skill，避免团队能力不一致。

• 精简维护迭代：定期清理废弃Skill、合并重复能力，避免项目Skill数量臃肿、管理混乱。

6.8 自建Skill安全自查清单

• SKILL.md 无未声明的高危工具调用（Write/Bash等）

• scripts 脚本无强制删除、批量清空等危险命令

• 所有文件无外部恶意链接、隐私数据

• 路径、配置无硬编码本地隐私信息

七、Skill Creator 辅助工具使用

Anthropic官方推出的Skill Creator工具，可辅助开发者快速生成、评测、优化Skill，大幅降低开发门槛、缩短迭代周期，适合新手快速上手、批量优化技能，具体使用流程与规范如下：

说明：Skill Creator本质上是Anthropic官方发布的一个特殊"元技能（meta-skill）"/插件，目前主要在 Claude Code 中使用，并非独立的网页应用或单独安装的客户端软件。使用前需先通过 /plugin install skill-creator 安装该插件（或参考skills仓库的plugin marketplace机制），安装完成后在 Claude Code 中输入 /skill-creator 即可唤起，按提示选择Create（创建）、Eval（评测）、Improve（优化）、Benchmark（对比测试）四种模式之一进行交互。

1. 核心流程：对话描述任务 → 工具生成初稿 → 补充细节 → 批量评测用例 → 输出评估报告；

2. 两大评估维度

   • 触发评估：生成正例、反例、边界用例，计算准确率、召回率；

   • 效果评估：对比 “有 Skill / 无 Skill” 的输出差异，统计通过率、Token 消耗；

3. 使用建议：工具生成仅作为初稿，人工补充边界规则、避坑要点后再正式上线。

八、Skill 开发常见错误、根因与解决方案（实战排错大全）

高频错误排错速查表

问题现象	根本原因	解决方案
技能完全无法加载（无报错、不识别）	文件夹名与 YAML name 不一致、主文件非 SKILL.md、路径含中文/Windows反斜杠、存放目录错误	统一 kebab-case 命名；修正文件名为全大写 SKILL.md；使用标准相对路径；放到对应平台 Skill 目录并重启工具
加载成功，但不会自动触发	description 描述宽泛模糊、无场景约束、priority 优先级过低	重构 description，包含功能+触发+禁用场景；核心技能优先级设 80–95
技能乱触发、抢占触发、多技能冲突	场景重叠、缺少禁用场景、优先级设置混乱	遵循单一职责拆分技能；补充禁用场景；拉开同类技能优先级差距
执行结果不稳定、时好时坏、步骤遗漏	步骤描述口语化/模糊、缺少检查点、约束强度不匹配	统一使用指令式祈使句；补充前置/过程检查点；标准化流程改用低自由度强约束
YAML 元数据解析报错、配置不生效	冒号后无空格、缩进混乱、存在冗余字段、description 超长	遵循标准 YAML 语法；删除非官方自定义字段；精简描述至 1024 字符内
权限过大引发误操作风险	未配置 allowed-tools，默认开放全部工具权限	遵循最小权限原则，按需分配工具权限，纯文案类关闭所有读写/执行权限
上下文臃肿、Token 消耗过高、响应卡顿	违背三级加载机制，资源全部常驻、正文内容冗余	长文档/脚本移入 L3 资源目录；控制 L2 正文在 5000 Token 内；清理无效内容
硬编码静态内容，换环境直接失效	写入本地绝对路径、固定账号、密钥、环境参数	禁用硬编码敏感/路径信息；使用相对路径；可变配置放入参考文档
缺少边界兜底，异常场景直接崩溃	仅适配正常用例，无异常/边界处理逻辑	优先设计负面、边界用例；完善失败处理策略，全场景兜底
技能大杂烩、功能堆砌，逻辑彻底混乱	一个 Skill 承载多个无关任务，违反单一职责	按业务职责拆分为独立 Skill；复杂流程使用主 Skill + 子 Skill 组合

8.1 技能完全无法加载（无报错、不识别）

错误现象：文件目录正常、SKILL.md 文件存在，但 AI 工具无法扫描、加载技能，也不支持手动调用。

根本原因：

• 最高频问题：Skill 文件夹名称与 YAML 中 name 字段命名不统一；

• 主文件命名不规范：非全大写 SKILL.md，存在大小写混用、拼写错误等问题；

• 路径格式不兼容：目录层级过深、路径包含中文/空格/Windows 反斜杠，导致跨平台读取失效；

• 文件存放路径错误：未放置在 Cursor、Claude Code 官方认可的 Skill 识别目录下。

解决方案：

• 统一命名规则：严格保证文件夹名与 YAML name 字段完全一致，全程采用小写 kebab-case 格式命名；

• 修正核心文件名：将主文件强制修改为纯大写 SKILL.md，无任何字符修改、大小写调整；

• 标准化路径格式：统一使用 Linux 正斜杠相对路径，清除路径内中文、空格、特殊符号；

• 规范存放目录：项目级技能放入对应平台项目目录（Cursor：.cursor/skills/、Claude Code：.claude/skills/），全局技能放置软件默认全局目录，修改完成后重启工具重载技能。

根本原因：

• 最高频问题：Skill 文件夹名称与 YAML 中 name 字段命名不统一；

• 主文件命名不规范：非全大写 SKILL.md，存在大小写混用、拼写错误等问题；

• 路径格式不兼容：目录层级过深、路径包含中文/空格/Windows 反斜杠，导致跨平台读取失效；

• 文件存放路径错误：未放置在 Cursor、Claude Code 官方认可的 Skill 识别目录下。

• 规范存放目录：项目级技能放入对应平台项目目录（Cursor：.cursor/skills/、Claude Code：.claude/skills/），全局技能放置软件默认全局目录，修改完成后重启工具重载技能。

8.2 加载成功，但不会自动触发

错误现象：技能列表可正常查看，手动调用可用，但对应业务场景下不会自动触发。

根本原因：

• description 描述过于宽泛、模糊，无精准业务关键词，AI 无法语义匹配；

• 未定义适用场景、禁用场景，语义边界模糊，模型不敢随意触发；

• 技能 priority 优先级过低，被系统默认规则、其他技能覆盖。

解决方案：

• 重构 description，必须包含「核心能力+精准触发场景+明确禁用场景」三要素，字数控制在1024字符内；

• 核心业务技能（代码校验、日志排查）优先级设置 80–95，工具类技能设置 60–75；

• 补充场景限定，规避语义模糊导致的触发失效。

8.3 技能乱触发、抢占触发、多技能冲突

错误现象：执行文档格式化、普通提问等操作时，代码审查、参数校验等无关技能错误触发，多技能互相抢占执行。

根本原因：

• 多个 Skill 语义场景重叠，无专属场景隔离；

• 未配置禁用场景，缺少边界约束；

• 优先级设置混乱，低优先级工具技能抢占核心业务技能。

解决方案：

• 严格遵循单一职责，一个技能只服务一类场景；

• 每个 Skill 强制补充 ❌ 禁用场景，精准隔离无关业务；

• 同类场景技能拉开优先级差距，核心技能优先级统一拉高，避免冲突抢占。

8.4 执行结果不稳定、时好时坏、步骤遗漏

错误现象：相同指令、相同场景，有时执行完整、有时遗漏步骤、有时输出混乱，随机性极强。

根本原因：

• 技能步骤描述口语化、模糊化，非指令式祈使句，AI 自主解读空间过大；

• 缺少前置检查、过程检查点、结果校验逻辑；

• 强约束业务使用高自由度设计，规则约束不足。

解决方案：

• 所有执行步骤统一改为指令式、一步一动作，删除概括性、主观性描述；

• 补齐「前置校验+分步执行+结果检查+异常兜底」完整流程；

• 固定流程、标准化业务改为低自由度强约束设计，杜绝随机输出。

8.5 YAML 元数据解析报错、配置不生效

错误现象：技能加载提示配置异常，priority、allowed-tools、user-invocable 等配置全部失效。

根本原因：

• YAML 语法不规范，冒号后无空格、缩进混乱、层级错乱；

• 自定义官方不支持的冗余字段，导致解析异常；

• description 超长、含特殊符号、换行混乱。

解决方案：

• 严格遵循 YAML 标准语法，统一2空格缩进，所有冒号后必须加空格；

• 仅保留官方支持字段，删除所有自定义无效字段；

• 精简 description 内容，控制字符长度，规范换行格式。

8.6 权限过大引发误操作风险

错误现象：文案类、格式化类技能，自动读取本地文件、执行脚本、修改代码，出现非预期操作。

根本原因：未配置allowed-tools 权限，技能默认开启全部工具权限，无权限隔离。

解决方案：

• 遵循最小权限原则，按需配置工具权限；

• 纯文案、排版、规则类技能，关闭 Read、Bash、文件修改等所有权限；

• 仅代码审查、脚本执行类技能按需开放对应权限。

8.7 上下文臃肿、Token 消耗过高、响应卡顿

错误现象：启用自定义技能后，对话响应变慢、Token 消耗激增、上下文冗余严重。

根本原因：

• 违背三级加载机制，大量脚本、参考文档、冗余规则常驻 L1/L2 上下文；

• SKILL.md 堆砌大量科普内容、重复规则、无效案例；

• 未拆分 L3 按需加载资源，所有内容常驻内存。

解决方案：

• 精简 L1 元数据，name控制在64字符内、description控制在1024字符内完成核心描述；

• 控制 L2 主体内容Token消耗（官方建议5000 Token以内），超长脚本、规范文档全部下沉到 scripts、references 目录；

• 清理冗余科普内容，仅保留执行必需规则，轻量化常驻上下文。

8.8 硬编码静态内容，环境变更直接失效

错误现象：本地测试正常，换设备、换项目、换环境后技能直接报错、无法执行。

根本原因：技能中硬编码本地绝对路径、固定账号、密钥、环境参数、版本信息。

解决方案：

• 禁止所有敏感信息、本地固定路径硬编码；

• 可变环境参数、配置统一放入 references 配置文件；

• 所有路径使用相对路径，适配多设备、多环境。

8.9 缺少边界兜底，异常场景直接崩溃

错误现象：正常场景执行正常，遇到空输入、空文件、非法参数、破损代码时，技能无输出、报错中断、卡死。

根本原因：仅适配正向正常用例，未设计边界用例、异常用例，无失败兜底策略。

解决方案：

• 开发阶段优先设计负面用例、边界用例，再适配正常场景；

• 全覆盖兜底：空内容、非法参数、文件缺失、代码破损、脚本报错等场景；

• 每个技能必须配置完整的失败处理策略，杜绝执行中断卡死。

8.10 技能大杂烩、功能堆砌，逻辑彻底混乱

错误现象：一个技能兼顾代码审查、单测生成、文档格式化、日志排查，执行逻辑混乱、输出错乱、AI 无法识别核心任务。

根本原因：违背单一职责原则，多类无关功能堆砌在同一个 Skill，属于典型反模式。

解决方案：

• 强制拆分功能，一个技能只负责一类核心任务；

• 复杂业务拆分为「主 Skill + 多个子 Skill」组合实现；

• 清理冗余功能，重构技能逻辑，保证职责单一、执行精准。

九、总结与生产级上线自查清单

9.1 核心总结

纵观整套AI Agent Skill工程化开发体系，相较于一次性Prompt，Skill的核心优势是可沉淀、可复用、可迭代、高稳定，其开发核心逻辑可浓缩为三大核心要点，贯穿全文所有规范与案例：

1. 元数据定生死：name 与 description 决定触发成功率，是第一优先级；

2. 步骤控执行：清晰指令 + 检查点 + 失败策略，保证执行不跑偏；

3. 架构保维护：合理拆分目录、单一职责、版本管理，适配长期迭代。

为方便开发者上线前零遗漏自检，规避99%的开发误区，结合官方开源规范与实战经验，整理出生产级Skill上线终极自查清单，开发完成后逐项核验，即可完全符合团队工程化标准：

• 文件夹名与YAML中name字段完全一致，严格遵循kebab-case小写命名规范；

• Description字段包含功能、触发场景、禁用场景，语义无歧义、字符长度合规；

• 正文全部为指令式步骤，配置完整检查点、异常兜底、失败处理逻辑；

• 严格遵循单一职责，无功能堆砌、无大杂烩技能设计，复杂场景已拆分父子技能；

• 全程无硬编码路径、密钥、时效信息，路径跨平台兼容、权限按需配置；

• 补充Gotchas避坑规则，精准覆盖AI高频误判、漏执行场景；

• 完成正向、边界、反向全用例测试，触发精准、执行稳定、输出合规。

---

学习资源

1. Agent Skills 开放标准官网：https://agentskills.io/
   核心价值：2025年12月 Anthropic 正式开放的 Agent Skills 跨平台官方开放标准站点，为 Cursor、Claude Code、GitHub Copilot 等全平台统一 Skill 规范基准，收录官方标准化定义、跨平台兼容协议、行业统一最佳实践、生态适配标准，是所有自定义 Skill 跨平台通用、规范化落地的权威依据。

2. 源码仓库： https://github.com/anthropics/skills
   核心价值：本文全部目录规范、三级渐进式加载机制、YAML元数据语法、开发最佳实践、官方反模式案例、工程化设计理念，均基于该官方开源仓库编写。内含大量生产级Skill模板、完整目录示例与官方避坑指南，是国内开发者可直接复用、查阅、落地的第一权威资源。

3. Claude API Docs： https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview
   核心价值：Anthropic 官方正统 Agent Skills 产品主页，更新时效最新，完整定义产品能力、预置技能清单、自定义技能通用规则、跨平台适配逻辑，是Skill体系核心权威基准文档。