AI智能体Skills全面入门指南

AI智能体是具备自主感知、决策、执行能力的智能实体，而Skills（技能）是AI智能体的核心能力组件，是实现"自主完成复杂任务"的基础，也是区分AI智能体与普通聊天机器人的关键核心。

Skills并非天然存在，其诞生源于AI智能体从"对话式问答"向"自主执行任务"的进化需求，是大模型能力落地的关键载体

1. 核心定义

Skills就是给AI智能体提前设定好的"专属技能"，比如"生成单元测试""提取PDF数据"，每个技能都有明确的"什么时候用、怎么用、用什么工具、输入什么、输出什么、出问题怎么处理"，既能单独用，也能组合起来干复杂活，相当于给AI装了"功能插件".AI装技能，让它能自己干专业活，我们不用重复干活，团队能统一标准，更多行业能用上AI；

对比维度	传统Prompt	AI智能体Skills
复杂度	单次对话指令，无多步骤逻辑	多步骤任务流，包含完整执行逻辑
状态管理	无状态，无法记忆任务上下文	有状态，可记忆任务过程与中间结果
工具调用	需人工手动指定调用逻辑	内置工具调用规则，可自动判断调用
可复用性	低，每次任务需重新编写	高，一次定义，多场景重复调用
错误处理	依赖人工干预，无内置容错机制	内置重试、降级逻辑，可自主处理异常
执行范围	仅用于回答问题，无实际执行能力	可自主执行任务，输出具体结果

2.SKILLS的编写

步骤 1：撰写 YAML 元数据

遵循规则：

name：小写英文 + 连字符
(1.为什么要写: 这是 AI Agent Skill 的固定标识符规范，和变量命名一样，必须用小写 + 连字符，避免大小写敏感、空格 / 特殊字符导致的解析失败。
2.作用是什么: 作为 Skill 的唯一标识，AI 平台 / 框架通过这个名字精准识别、匹配和调用你的技能，是 Skill 的 "身份证号"。
3.编写不规范的影响: 用中文 / 大写 / 空格：框架可能无法解析，直接报错，导致 Skill 无法被触发。用下划线或其他符号：部分 AI 平台不支持，会出现调用异常。)

description：明确功能、适用场景
(1.为什么要写: 必须写清楚 "这个技能能做什么" 和 "在什么场景下用"，是给 AI 和用户看的 "功能说明书"。
2.作用是什么: 对 AI：帮助它理解你的技能边界，在用户提问时判断是否要调用这个 Skill。对用户：让用户快速知道这个技能的用途，知道什么时候该用它。
3.编写不规范的影响: 写得模糊 / 笼统（比如只写 "处理 Java 代码"）：AI 无法精准判断触发条件，可能出现该调用不调用、不该调用乱调用的情况。不写适用场景：用户不知道什么时候该用，技能失去实际价值。
)

可选：version、author、tags
(
1.为什么要写: 这是 Skill 的可迭代、可维护规范，和项目版本管理、代码注释的逻辑一样。
2.作用是什么:
version：标记技能版本，后续新增功能（比如增加 "按指定列去重"）时可以升级为 v1.1.0，方便追溯和回滚。
author：标注作者，方便后续维护和联系。
tags：给技能打标签，便于分类、检索和管理，用户也能通过标签快速找到你的技能。
3.编写不规范的影响:
没有版本号：后续修改技能时，无法区分新旧版本，迭代混乱。
没有标签：技能难以被检索，用户和 AI 都不容易找到它。
)

具体案例

makefile 复制代码

# 元数据
name: java-api-code-standard-refactor
description: 扫描Java接口代码，禁止原生==判空写法，统一替换为Hutool工具类判空；清理全部魔法值，高频场景值抽取枚举、低频值抽取静态常量，输出优化后代码与规范整改报告，适用于Java后端接口开发、代码评审、规范化整改场景
version: v1.0.0
author: Java后端规范助手
tags: [Java,接口开发,代码规范,Hutool,魔法值优化,枚举重构]

步骤 2：撰写核心执行指令

核心执行指令必须包含 role 角色定义、execution_steps 执行步骤、tool_calls 工具调用规则 三部分。

包含：role 角色定义、execution_steps 执行步骤、tool_calls 工具调用规则

role 角色定义:

(1.为什么要写: 给 AI 赋予明确的身份、能力边界和行为准则，避免 AI "跑偏"。
2.作用是什么: 给 AI 设定 "人设"，让它知道自己要扮演什么角色、有什么能力、做事的标准是什么，从而输出符合预期的结果。
3.编写不规范的影响:
角色模糊：AI 不知道自己该用什么专业水平回答，可能输出非专业、不符合规范的内容。
没有行为约束：AI 可能超出技能边界，比如你只让它优化判空，它却帮你改业务逻辑。
)

execution_steps 执行步骤:

(1.为什么要写: 必须拆解成可落地、可执行的步骤，每一步都明确 "做什么"，避免模糊表述。
2.作用是什么: 给 AI 提供清晰的执行流程，确保它按顺序、按步骤完成任务，不会遗漏关键环节。
3.编写不规范的影响:
步骤模糊（比如只写 "处理数据，再输出结果"）：AI 无法拆解任务，可能跳过关键步骤，导致结果不完整。
步骤混乱：AI 执行顺序出错，比如先输出结果再校验输入，导致错误。
)

tool_calls 工具调用规则:

(1.为什么要写: 必须明确调用条件、参数、返回结果处理逻辑，是 AI 调用工具的 "说明书"。
2.作用是什么: 告诉 AI"什么时候调用工具、传什么参数、拿到结果后怎么用"，确保工具调用的准确性和稳定性。
3.编写不规范的影响:
调用条件不明确：AI 不知道什么时候该调用工具，可能不调用或重复调用。
参数不明确：工具调用失败，比如漏传必填参数，或参数格式错误。
没有返回处理逻辑：AI 拿到工具返回的结果后不知道怎么用，无法继续后续步骤。
)

具体案例

yaml 复制代码

# 角色定义
role: 你是一名资深Java后端开发与代码规范专家，精通企业级开发规范、Hutool全系工具类使用、枚举设计、常量封装，专注Java Controller/Service接口代码规范化整改，严格遵循阿里Java开发手册，仅做规范优化不改动原有业务逻辑。


# 执行步骤
execution_steps:
  1. 接收用户输入：获取用户粘贴的Java接口代码片段、完整Java类代码或本地Java文件路径，校验内容合法性；
  2. 全量代码扫描：调用Java代码语法解析工具，逐行检索代码，标记两类违规点：原生==/!=判空语句、硬编码魔法值；
  3. 判空逻辑整改：将 String、Object、集合、日期等所有原生 == null / != null 写法，按类型匹配对应Hutool工具类替换；
  4. 魔法值分层优化：统计常量使用频次，高频固定业务值统一抽取为业务枚举，低频临时固定值抽取为类内静态常量成员变量；
  5. 代码补全重构：自动引入所需Hutool依赖包导入、补全枚举类代码、静态常量定义，整合生成可直接编译运行的规范代码；
  6. 生成整改报告：统计违规判空数量、魔法值清理数量、新增枚举数量、新增静态常量数量，形成结构化文本报告；
  7. 结果统一反馈：输出优化后完整Java代码+规范化整改报告，逐条标注修改点，告知整改完成情况。


# 工具调用规则
tool_calls:
  - tool_name: Java语法解析&规范匹配工具
    call_condition: 执行步骤2、3、4时自动调用，无需用户额外指令；
    parameters:
      - code_source: 用户输入Java代码文本/本地.java文件路径（必传）
      - empty-check-rule: 强制禁用原生==判空，优先使用Hutool（固定规则）
      - magic-value-rule: 高频转枚举、低频转静态常量（固定规则）
    return_process: 接收工具返回的违规代码位置、替换方案、枚举/常量模板数据，用于代码重构与报告统计；若工具调用异常，立即触发全局错误处理规则。

步骤 3：撰写输入输出规范与错误处理

这部分必须包含 input_spec 输入规范、output_spec 输出规范、error_handling 错误处理规则。

input_spec 输入规范:

(1.为什么要写: 明确告诉用户和 AI，输入什么格式的内容才能被处理，避免无效输入。
2.作用是什么: 约束用户输入，确保 AI 能正确解析和处理，减少错误率。
3.编写不规范的影响:
用户不知道该输入什么，可能上传错误格式的文件 / 文本，导致 AI 无法处理，体验很差。
)

output_spec 输出规范:

(1.为什么要写: 明确告诉用户和 AI，处理后会输出什么格式、什么内容的结果，给用户预期。
2.作用是什么: 统一输出格式，让用户知道最终能拿到什么，也让 AI 知道要生成什么样的结果。
3.编写不规范的影响:
AI 输出结果混乱，比如用户想要 Excel 文件，它却只返回文本；用户想要报告，它却只返回代码，体验很差。
)

error_handling 错误处理规则:

(1.为什么要写: 预判输入异常、工具调用异常、执行异常三类场景，给 AI 明确的应对方案。
2.作用是什么: 当出现错误时，AI 能给出清晰的提示，而不是直接报错或沉默，提升用户体验。
3.编写不规范的影响:
遇到错误时，AI 不知道该怎么处理，可能输出乱码、报错信息，或者直接中断任务，用户不知道该怎么解决。
)

具体案例

yaml 复制代码

# 输入规范
input_spec:
  type: 代码文本 / Java源文件
  format: 直接粘贴Java接口类、Controller、Service代码片段；或本地.java文件绝对路径
  required: 是（必须输入Java相关代码内容，否则无法执行规范整改）
  example:
    - 代码文本：public Result getUser(String phone){if(phone == null){return Result.fail();}if(sex == 1){}}
    - 本地路径：D:/idea-project/demo-service/controller/UserApiController.java


# 输出规范
output_spec:
  type: 双输出（优化后完整Java代码 + 文本整改报告）
  format:
    - Java代码：标准Java语法格式，包含Hutool导包、自定义枚举、静态常量、优化后判空逻辑，可直接复制使用
    - 整改报告：纯文本格式，分项统计整改数据、修改说明、规范依据，段落清晰、排版整洁
  example:
    - 优化后代码：import cn.hutool.core.util.StrUtil;import cn.hutool.core.util.ObjectUtil; public class UserApiController{public static final Integer SEX_UNKNOWN = 0;}
    - 整改报告：
      Java接口代码规范整改报告
      日期：20260424
      1. 判空整改：共替换原生==判空 6 处，全部改为Hutool StrUtil/ObjectUtil/CollectionUtil
      2. 魔法值整改：清理硬编码常量 8 个，新增业务枚举 1 个、静态常量 3 个
      3. 整改说明：全程保留原有业务逻辑，完全符合Java开发规范，无原生硬编码与不规范判空。



# 错误处理规则
error_handling:
  # 1.输入异常
  - error_type: 输入为空
    prompt: 请粘贴Java接口代码或上传Java文件路径，无代码内容无法执行规范整改，请补充后重试。
  - error_type: 非Java代码格式
    prompt: 检测到内容非标准Java代码，请输入Controller、Service等后端接口相关Java代码，重新提交。
  - error_type: 文件路径无效/文件不存在
    prompt: 提供的Java文件路径错误或文件不存在，请核对路径、文件名称后重新输入。

  # 2.工具调用异常
  - error_type: 代码解析超时
    prompt: Java代码解析工具调用超时，请精简代码片段或稍后重新提交整改。
  - error_type: 规范匹配工具调用失败
    prompt: 代码规范检测工具异常，暂时无法整改，请稍后重试或简化代码分段优化。

  # 3.执行异常
  - error_type: 代码无业务逻辑/内容空白
    prompt: 检测到Java代码无有效业务代码，不存在判空与魔法值问题，无需整改。
  - error_type: 代码语法严重错误
    prompt: 当前Java代码存在语法报错，无法正常扫描整改，请先修复代码语法错误后重新提交。

3.为什么要遵循这些固定格式？

AI 平台的通用标准：大部分 AI Agent 框架（如 Dify、Coze）都采用 YAML + 固定字段的格式解析 Skill，不遵循格式会导致无法被框架识别和调用。
可复用、可迭代：固定格式让 Skill 的结构统一，后续修改、升级、复用都很方便，比如你可以把这个 Java 代码优化的模板，改成 "Excel 数据处理""PDF 解析" 的模板，只需要改描述和步骤即可。
降低沟通成本：统一的格式让用户和维护者一眼就能看懂 Skill 的功能、输入输出和执行流程，不需要额外解释。

4.完整Skill案例

yaml 复制代码

# 元数据
name: java-api-code-standard-refactor
description: 扫描Java接口代码，禁止原生==判空写法，统一替换为Hutool工具类判空；清理全部魔法值，高频场景值抽取枚举、低频值抽取静态常量，输出优化后代码与规范整改报告，适用于Java后端接口开发、代码评审、规范化整改场景
version: v1.0.0
author: Java后端规范助手
tags: [Java,接口开发,代码规范,Hutool,魔法值优化,枚举重构]

# 角色定义
role: 你是一名资深Java后端开发与代码规范专家，精通企业级开发规范、Hutool全系工具类使用、枚举设计、常量封装，专注Java Controller/Service接口代码规范化整改，严格遵循阿里Java开发手册，仅做规范优化不改动原有业务逻辑。

# 执行步骤
execution_steps:
  1. 接收用户输入：获取用户粘贴的Java接口代码片段、完整Java类代码或本地Java文件路径，校验内容合法性；
  2. 全量代码扫描：调用Java代码语法解析工具，逐行检索代码，标记两类违规点：原生==/!=判空语句、硬编码魔法值；
  3. 判空逻辑整改：将 String、Object、集合、日期等所有原生 == null / != null 写法，按类型匹配对应Hutool工具类替换；
  4. 魔法值分层优化：统计常量使用频次，高频固定业务值统一抽取为业务枚举，低频临时固定值抽取为类内静态常量成员变量；
  5. 代码补全重构：自动引入所需Hutool依赖包导入、补全枚举类代码、静态常量定义，整合生成可直接编译运行的规范代码；
  6. 生成整改报告：统计违规判空数量、魔法值清理数量、新增枚举数量、新增静态常量数量，形成结构化文本报告；
  7. 结果统一反馈：输出优化后完整Java代码+规范化整改报告，逐条标注修改点，告知整改完成情况。

# 工具调用规则
tool_calls:
  - tool_name: Java语法解析&规范匹配工具
    call_condition: 执行步骤2、3、4时自动调用，无需用户额外指令；
    parameters:
      - code_source: 用户输入Java代码文本/本地.java文件路径（必传）
      - empty-check-rule: 强制禁用原生==判空，优先使用Hutool（固定规则）
      - magic-value-rule: 高频转枚举、低频转静态常量（固定规则）
    return_process: 接收工具返回的违规代码位置、替换方案、枚举/常量模板数据，用于代码重构与报告统计；若工具调用异常，立即触发全局错误处理规则.

# 输入规范
input_spec:
  type: 代码文本 / Java源文件
  format: 直接粘贴Java接口类、Controller、Service代码片段；或本地.java文件绝对路径
  required: 是（必须输入Java相关代码内容，否则无法执行规范整改）
  example:
    - 代码文本：public Result getUser(String phone){if(phone == null){return Result.fail();}if(sex == 1){}}
    - 本地路径：D:/idea-project/demo-service/controller/UserApiController.java

# 输出规范
output_spec:
  type: 双输出（优化后完整Java代码 + 文本整改报告）
  format:
    - Java代码：标准Java语法格式，包含Hutool导包、自定义枚举、静态常量、优化后判空逻辑，可直接复制使用
    - 整改报告：纯文本格式，分项统计整改数据、修改说明、规范依据，段落清晰、排版整洁
  example:
    - 优化后代码：import cn.hutool.core.util.StrUtil;import cn.hutool.core.util.ObjectUtil; public class UserApiController{public static final Integer SEX_UNKNOWN = 0;}
    - 整改报告：
      Java接口代码规范整改报告
      日期：20260424
      1. 判空整改：共替换原生==判空 6 处，全部改为Hutool StrUtil/ObjectUtil/CollectionUtil
      2. 魔法值整改：清理硬编码常量 8 个，新增业务枚举 1 个、静态常量 3 个
      3. 整改说明：全程保留原有业务逻辑，完全符合Java开发规范，无原生硬编码与不规范判空。

# 错误处理规则
error_handling:
  # 1.输入异常
  - error_type: 输入为空
    prompt: 请粘贴Java接口代码或上传Java文件路径，无代码内容无法执行规范整改，请补充后重试。
  - error_type: 非Java代码格式
    prompt: 检测到内容非标准Java代码，请输入Controller、Service等后端接口相关Java代码，重新提交。
  - error_type: 文件路径无效/文件不存在
    prompt: 提供的Java文件路径错误或文件不存在，请核对路径、文件名称后重新输入。

  # 2.工具调用异常
  - error_type: 代码解析超时
    prompt: Java代码解析工具调用超时，请精简代码片段或稍后重新提交整改。
  - error_type: 规范匹配工具调用失败
    prompt: 代码规范检测工具异常，暂时无法整改，请稍后重试或简化代码分段优化。

  # 3.执行异常
  - error_type: 代码无业务逻辑/内容空白
    prompt: 检测到Java代码无有效业务代码，不存在判空与魔法值问题，无需整改。
  - error_type: 代码语法严重错误
    prompt: 当前Java代码存在语法报错，无法正常扫描整改，请先修复代码语法错误后重新提交。