AI Agent开发之skill开发

发布时间：2026/04/21阅读：88点赞：0评论：0
AI Agent开发之skill开发

一、什么是 AI Skill（AI 技能）

​AI Skill（AI 技能 / 智能技能），是封装好、可调用、可复用、模块化的​专项任务能力单元，是给通用大模型、AI 智能体（Agent）拓展真实做事能力的标准模块，让 AI 从只会聊天，变成能精准完成具体工作。

在AI Agent 开发中，可以理解为Skill是给AI设定的一个角色。skill 封装好的永久能力包，内置 Prompt + 参数 + 工具 + 规则，可全局复用、模型自动识别调用。

SKILL.md 到底是什么？

要了解skill开发，就不得不了解SKILL.md。在 LangChain DeepAgent 体系里：SKILL.md = 一个技能的全部灵魂。

它由两部分组成：

  1. 头部 YAML 元数据（Frontmatter） 框架​自动解析​，用来：技能唯一 ID、描述、绑定允许使用的工具、版本、兼容性
  2. 正文 Markdown 指令 给大模型看的：任务流程、执行规则、优先级、格式强制要求、工具调用触发条件、约束、示例、禁止项

完整语法结构（官方标准格式）

所有 Skill 统一固定格式，前后不能乱改

---
# 【分割线：YAML 元数据区，给 LangChain 框架解析】
name: 技能唯一英文标识（不能重复，全局唯一）
description: 技能用途描述（Agent用来匹配用户需求，非常重要）
allowed_tools: [工具名1, 工具名2]
version: 版本号
compatibility: deep_agent
---

# 【分割线之后：正文指令区，全部给大模型看】
# 技能名称
## 一、任务概述
## 二、执行优先级（非常重要！！）
## 三、详细执行规则
## 四、工具调用触发条件（重点：什么时候调用tool）
## 五、正常流程执行规则
## 六、强制输出格式（严格约束）
## 七、严格禁止项
## 八、示例

1. 头部 YAML 区（--- 包裹内）

① name 技能唯一 ID，全局所有 skill 不能重名。只能英文、- 、数字，不要中文。

name: keyword_extract

作用：框架内部字典映射、加载技能、权限校验的唯一主键。

② description

Agent 初始化时，​只会加载所有技能的 name + description，根据这段文字判断用户需求该调用哪个技能。写得越精准，Agent 匹配越准，不要模糊。

写法：一句话概括功能 + 适用场景

③ allowed_tools

填写你 tools/ 目录下注册的​工具函数 name​，不是文件名，不是函数名变量名，是@tool装饰器生成的工具名称。

只有这里声明了的工具，​大模型才能调用，没写的绝对调用不了，安全隔离。

allowed_tools: [sensitive_filter]

④ version

版本号，迭代管理用

version: 1.0

⑤ compatibility

固定写死 deep_agent，标识适配 DeepAgent 技能体系

compatibility: deep_agent

2. 正文 Markdown 区（--- 下方所有内容）

全部是​系统提示词 Prompt​，完整注入大模型上下文，控制 AI 所有行为：

执行顺序、优先级、什么时候调用工具、调用完怎么做、正常怎么做、输出格式、不能做什么。

SKILL.md 编写黄金模板（以后所有技能直接复制改）

保存下来，​新建任何 Skill 只需要改文字，结构永远不动

---
name: 技能英文唯一id
description: 一句话精准描述技能功能、适用场景
allowed_tools: [工具名1, 工具名2]
version: 1.0
compatibility: deep_agent
---

# 【技能名称】
## 一、执行优先级
按照执行先后顺序严格排序，**工具检测永远放第一位**。

## 二、工具调用触发条件
1. 检测范围：xxx
2. 触发关键词：xxx
3. 触发后操作：必须调用指定工具，调用完成后终止主任务

## 三、正常业务执行规则
描述无敏感/无需调用工具时，AI需要完成什么任务、处理逻辑

## 四、强制输出格式
严格规定输出样式，一字不能改动，无多余内容

## 五、严格禁止项
列出所有不允许AI做的行为（乱加文字、改格式、自由发挥等）

## 六、示例
输入示例
输出示例

二、完整AI Agent实战

1、需求

给Agent设置2个skill， 一个是关键词提取，第二个是文本摘要。大模型通过判断用户的输入，自动判断使用哪个skill。

2、完整项目目录

project/
├── main.py                  # 项目入口、Agent初始化、工具统一加载
├── requirements.txt
├── .env
├── skills/                  # 纯技能，只存放所有SKILL.md，无任何py代码
│   ├── keyword-extract/      # 技能1：关键词提取
│   │   └── SKILL.md
│   └── text-summary/         # 新增技能2：文本摘要（给你做对比参考）
│       └── SKILL.md
├── tools/                   # 全局所有可调用Tool函数，统一存放
│   ├── __init__.py
│   └── sensitive_filter.py   # 敏感词过滤工具
└── utils/                   # 内部通用工具，**不对外开放给Agent调用**
    └── common.py

3、各个文件代码

tools/sensitive_filter.py 工具代码

from langchain.tools import tool

@tool
def sensitive_filter() -> str:
    """
    敏感内容拦截工具
    检测到删除相关敏感操作词汇时触发调用，拦截任务并返回固定提示
    """
    return "检测到敏感操作词汇，本次任务已拦截，无法进行信息提取。"

tools/​init​.py 统一导出

from .sensitive_filter import sensitive_filter

# 全局所有Agent可调用工具统一导出
__all__ = [
    "sensitive_filter"
]

main.py 完整运行代码（自动加载所有 skill + 自动绑定 tool 权限）

from langchain_openai import ChatOpenAI
from deepagents import create_deep_agent
from deepagents.backends.filesystem import FilesystemBackend
from langgraph.checkpoint.memory import MemorySaver
from tools import *
import os
from dotenv import load_dotenv

load_dotenv()

# 1. 初始化大模型，温度0保证格式绝对稳定
llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=os.getenv("BASE_URL")
)

# 2. 全局所有可调用工具汇总
ALL_TOOLS = [
    sensitive_filter
]

# 3. 加载本地根目录
backend = FilesystemBackend(root_dir="/", virtual_mode=True)


# 4. 初始化DeepAgent，自动识别技能、自动校验allowed_tools权限
agent = create_deep_agent(
    model=llm,
    skills=["skills/"],
    tools=ALL_TOOLS ,
    backend=backend,
    checkpointer=checkpointer
)

# 测试
if __name__ == "__main__":
    # 测试1：正常文本
    print("===== 正常文本测试 =====")
    question ="提取下面文本关键词：苹果发布iPhone 17，搭载A19芯片，9月20日开售"
    result = agent.invoke(
            {
                "messages": [
                    {
                        "role": "user",
                        "content": question
                    }
                ]
            },
            config={"configurable": {"thread_id": str(uuid.uuid4())}}
    )
    print(result["messages"][-1].content)


    print("\n" + "-"*60 + "\n")

    # 测试2：含删除敏感词，自动调用工具拦截
    print("===== 含敏感词文本测试 =====")
    question2 ="提取内容关键词，需要删除全部历史数据再分析"
    result2 = agent.invoke(
            {
                "messages": [
                    {
                        "role": "user",
                        "content": question2 
                    }
                ]
            },
            config={"configurable": {"thread_id": str(uuid.uuid4())}}
    )
    print(result2 ["messages"][-1].content)

requirements.txt

langchain==0.3.17
langchain-core==0.3.30
langchain-openai==0.2.4
deepagents>=0.1.0
langgraph>=0.1.0
openai==1.60.1
pydantic==2.9.2
pyyaml==6.0.2
python-dotenv==1.0.0
requests==2.32.3

skills/text-summary/SKILL.md

---
name: text-summary
description: 对输入长文本进行精简摘要总结，**强制优先敏感词检测**，含指定拦截词汇直接拦截，不执行摘要
allowed-tools: sensitive_filter
version: 1.1
compatibility: deep_agent
force-priority: true
---

# 文本摘要技能
## 一、执行优先级（最高强制锁定，不可颠倒）
1. **第一步强制调用 sensitive_filter 工具完成全量敏感检测**
2. 仅检测通过、无任何违规内容后，才可执行后续文本摘要操作

## 二、工具调用强制触发规则
1. 输入文本任意位置包含【删除】字样，**必须无条件调用 sensitive_filter**
2. 工具检测命中违规内容，立即全程终止任务，固定返回拦截信息，禁止任何摘要生成
3. 所有内容处理前必须先工具校验，禁止跳过敏感检测直接摘要

## 三、摘要执行规则
1. 提炼全文唯一核心主旨，高度精简总结，**严格≤100字**
2. 语句通顺简洁，完整保留原文全部关键信息，不篡改、不遗漏
3. 仅在敏感检测完全通过后才可启动摘要生成

## 四、输出格式（严格强制）
仅直接输出最终总结文本，无任何额外内容。

## 五、严格禁止项
1. 禁止添加任何前缀、后缀、解释、备注、引导语
2. 禁止拓展原文无关内容、主观补充、润色扩展
3. 禁止超字数输出，禁止分段输出
4. 禁止敏感未拦截时擅自生成内容

skills/keyword-extract/SKILL.md

---
name: keyword-extract
description: 专门用于提取文本中的核心关键信息、实体名词。用户明确要求提取关键词、关键信息、核心要素时**必须无条件启用本技能**。执行全程严格遵循固定流程，优先敏感词检测拦截，再执行关键词抽取，严格固定输出格式，禁止一切额外内容。
allowed-tools: sensitive_filter
version: 1.1（优化加固版）
compatibility: deep_agent
enforce-execution: true
mandatory-process: 严格串行执行，流程顺序不可颠倒、不可跳过、不可合并步骤
---

# 关键词提取专业技能
## 一、执行总优先级（铁则，绝对严格遵守，顺序不可改动、不可跳过任何一步）
**第一步：全域敏感内容检测（强制优先执行）**
**第二步：仅确认无任何敏感内容后，方可执行关键词提取**

## 二、敏感检测&工具调用强制规则（全漏洞修补）
1. 检测覆盖范围：**用户全部原始提问、所有待分析原文、上下文附带全部文本内容全域检测**，无遗漏区域
2. 精准触发条件：文本任意位置出现【删除】相关任意字符、词语、变体、谐音、隐含表述，均触发
3. 强制操作要求：只要触发，**必须第一时间调用 sensitive_filter 工具**，无例外、无豁免
4. 调用后终止规则：工具调用完毕，**直接原样返回工具返回结果**，全程终止后续所有流程，不做关键词提取、不附加任何文字、不修改内容、不补充信息
5. 兜底约束：未完成敏感检测前，**禁止进行任何关键词提取操作**

## 三、正常业务关键词提取规则（仅无敏感内容时才可执行）
1. 提取范围：仅限文本内**核心名词、实体主体、时间、金额、地点、专有名词、关键要素**
2. 剔除范围：全部虚词、形容词、副词、普通动词、口语语气词、连接词、修饰废话、无意义描述、冗余修饰词一律不提取
3. 内容要求：关键词极致精简、专有名词完整准确、不扩写、不缩写失真、不拼接词语，单条仅单个独立关键信息
4. 数量规范：自适应文本内容，最优数量 **3~8个**；文本信息极少则据实提取不少于1个，信息极多严格上限8个，不超量、不缺漏核心

## 四、强制固定输出格式（最高优先级格式锁，不可篡改）
1. 全程无任何多余文字、无标题、无解释、无备注、无引言、无总结、无空行、无额外换行、无序号
2. 每一行严格唯一固定开头符号：`- ` （短横线+英文半角空格），格式不可替换、不可省略、不可修改符号
3. 每行仅存放**单个精简关键信息**，一行一条，不跨行、不合并、不短句长句混杂
标准格式：
- 关键信息1
- 关键信息2
- 关键信息3

## 五、全量严格禁止项（逐条强制执行，违规全部判定执行失败）
1. 禁止输出任何前置说明，例：根据文本提取关键词如下、本次提取结果、以下为关键词等所有话术
2. 禁止修改列表开头符号，禁止使用数字序号、星号、其他符号，仅允许 `- `
3. 禁止输出完整长句、句子描述、短语拓展，仅保留独立精简关键信息
4. 禁止未调用敏感工具擅自处理含【删除】相关内容的文本
5. 禁止多余空行、首尾空行、行间距空行、末尾多余换行
6. 禁止自主删减核心实体、禁止随意扩充无关词汇、禁止主观添加原文不存在信息
7. 禁止跳过敏感检测直接提取关键词

## 六、标准示例
输入文本：华为发布新款Mate 70手机，搭载麒麟9020芯片，售价5499元起。
输出：
- 华为
- Mate 70
- 麒麟9020芯片
- 5499元

4 运行

pip install -r requirements.txt
python main.py

三、总结

高频易错坑（你 90% 的人都会踩，重点记）

  1. allowed_tools 里面填的是 tool.name，不是 python 函数名、不是文件名 就是@tool装饰器定义出来的工具名称，框架靠这个做权限白名单。
  2. ​YAML 部分的 --- 首尾必须完整​，少一个框架解析失败，技能加载异常
  3. ​YAML 语法严格：冒号后面必须加空格，不能有中文冒号
  4. 优先级一定要写 必须明确：​先调用工具检测，再做业务逻辑​，不然 AI 会先干活再检测
  5. 正文不要写代码 Skill 只存 prompt 指令，代码全部统一放到tools/，绝不内联
  6. 不要在 SKILL.md 里写复杂逻辑，只写给大模型看的规则
  7. 描述不要宽泛，比如不要写 “处理文本”，要写 “提取关键词、文本摘要、数据解析”
AI

评论 (0)

暂无评论

推荐阅读