Agent Skills实战：手写技能包，用本地模型搭建离线AI代理

1. 为什么“专业技能包”成了AI代理的瓶颈

过去一年我试过不少AI代理框架，从个人项目里的简单工具链，到团队内部跑的自动化流程，几乎都撞上同一个天花板：模型本身很聪明，但代理能做的事，完全取决于你给它塞了多少“干活的本事”。你可以让GPT-4或Claude写一首诗、解一道微积分，但你想让它帮你查一下Outlook里未读邮件、把Excel里某列数据做透视表、再根据结果发一封Teams消息——它就傻眼了。原因很简单，模型只负责“思考”，不负责“动手”，动手的能力得靠外部工具、API、插件一个个接进去。

这就是我关注Microsoft Agent Skills的原因。它的定位很直接：把代理能用的能力打包成一个个可复用、可组合、可分享的“专业技能包”，让AI代理不再裸奔，而是像一个有多年经验的老员工，随取随用各种业务工具。微软在Build 2025上把它作为Agent Framework的一部分推了出来，但单独看Agent Skills这个概念，其实适用面比框架本身更广——你甚至可以在Semantic Kernel、AutoGen里用同样的思路组织你的代理能力。

打个比方，以前的AI代理像个刚毕业的大学生，脑子好使但啥都不会干；你教它一个技能，它就会一个。Agent Skills要做的事情，是给这个大学生发一本厚厚的SOP手册，里面分门别类写好了“怎么做Excel透视表”“怎么调用公司内部API”“怎么处理PDF发票”，要用的时候直接翻到对应章节照着干。这个比喻基本就是Agent Skills的设计哲学：技能不再是零散的提示词或代码片段，而是有结构、有描述、有输入输出定义的标准化单元。

这篇文章我打算从实际落地角度拆一拆Agent Skills到底是个什么东西、它和普通提示词/插件有什么区别、怎么自己动手写一个技能包，以及最关键的——怎么用“本地模型+Agent Skills”搭一套完全离线、隐私安全的代理助手。这个组合是我最近实验的重点，也是我觉得最值得分享的部分。

2. 核心概念拆解：Agent Skills到底是什么

2.1 从“给模型提示词”到“给代理发技能包”

要理解Agent Skills，得先理清它和传统提示词工程的根本区别。过去我们让模型完成特定任务，通常是在System Prompt里写一大段详细的指令，告诉它“你是一个数据分析助手，你需要做以下步骤……”这种方式对简单的、单轮的任务确实够用，但一旦任务链条变长、涉及多步骤工具调用，提示词就会变得臃肿不堪，而且每换一个场景就要重新写一大段，复用性极差。

Agent Skills的思路是反过来的。它不再把“技能”当作模型上下文里的一段文字，而是当作一个独立的、可加载的模块。每个技能包包含三样核心东西：一份给模型看的技能描述（告诉它这个技能是干什么的、什么时候该调用），一套可执行的代码逻辑（真正去调用API、处理数据、操作文件），以及一个清晰的输入输出规范（让模型知道该传什么参数、能拿回什么结果）。

这套设计解决了几个我之前踩过的坑。第一个是上下文污染问题：以前我把十几个工具的说明全塞进System Prompt，模型经常混淆工具之间的边界，明明该调A工具却去调B工具。Agent Skills可以按需加载，模型先根据任务判断需要哪个技能，再去读取对应技能的描述和代码，上下文里始终只保留当前任务相关的信息。第二个是复用问题：我写好的技能包可以导出成文件，在另一个项目里直接导入，甚至分享给团队同事，不用每次从零开始写提示词。

2.2 技能包的三层结构：描述、代码、规范

具体来说，一个标准的Agent Skills包通常包含以下几个部分：

这个结构跟我们写普通代码时的“模块化”思路一脉相承，只不过服务的对象从“人类程序员”变成了“AI代理”。SKILL.md是整个技能包的大脑，它决定了模型能不能正确理解和使用这个技能。写得好的SKILL.md，应该像一份优秀的API文档，既说明了功能边界，又给了清晰的使用示例。

2.3 和Plugins、Tools、MCP的关系

这个话题在社区里讨论很多，我一开始也绕晕了。简单理一下我的理解：Tools是最底层的概念，就是单个的函数调用；Plugins是Tools的集合，通常绑定在特定平台上；MCP是一种统一工具接入协议，让不同的代理框架都能调用同一套工具；而Agent Skills更侧重于“技能的封装与编排”，它不关心底层工具怎么接入，关心的是“怎么让代理在正确的时间用正确的方式使用这些工具”。

做个不太严谨但容易理解的对比：Tools就像积木块，Plugins是装好的一盒积木，MCP是统一的积木接口标准，Agent Skills则是一张拼装说明书——它告诉你某种能力该怎么组合底层积木来实现完整任务。实际开发中它们并不冲突，完全可以混用：Agent Skills的内部代码可以调用MCP服务器提供的工具，也可以直接封装几个Tools。

3. 手写一个Agent Skills包：完整实操记录

3.1 环境准备与项目结构

我建议直接用微软提供的Agent Skills示例仓库作为起点，或者按照官方文档手动搭建目录结构。这里我以Python为例，展示一个最精简但完整的技能包长什么样：

text复制my-skill/
├── SKILL.md
├── skill.py
└── requirements.txt

就这么简单，三个文件。SKILL.md负责给模型看，skill.py负责真正干活，requirements.txt声明依赖。如果技能逻辑比较复杂，你也可以在目录下建子模块，但核心就这三样。

命令行下直接创建项目目录并初始化Python虚拟环境：

bash复制mkdir my-skill && cd my-skill
python -m venv .venv
source .venv/bin/activate  # Windows下用 .venv\Scripts\activate
pip install semantic-kernel

3.2 编写SKILL.md：给模型看的“使用说明书”

很多人第一次写SKILL.md容易走两个极端：要么写得像天书，全是术语；要么写得像流水账，没有任何关键信息。我的经验是，这份文档的核心读者是“语言模型”，所以要写得清晰、结构化、有示例，同时避免歧义。

以一个“CSV数据统计分析”技能为例，我会这样写SKILL.md：

markdown复制# CSV Data Analyzer

## Description
Analyze a CSV file and return statistical summaries including mean, median, standard deviation for numeric columns, and value counts for categorical columns.

## When to use
Use this skill when the user asks to analyze data contained in a CSV file, or when they ask for statistical summaries of tabular data.

## Parameters
- file_path: string, required. Absolute path to the CSV file.
- delimiter: string, optional. Defaults to ",".

## Output
A JSON object with keys: columns, numeric_stats, categorical_stats.

## Example
User: "分析一下sales.csv这份销售数据"
Agent: {"columns": ["date", "revenue", "region"], "numeric_stats": {"revenue": {"mean": 12345.6, "median": 11000.0, "std": 3200.1}}, "categorical_stats": {"region": {"East": 12, "West": 9, "North": 7, "South": 6}}}

注意几个关键点：Description要简洁但信息完整；When to use部分不要写得太窄，否则模型会漏掉该用的时候；Parameters要给出类型和默认值，避免模型瞎猜；Example最好给一个从用户请求到JSON输出的完整示例，模型会模仿这个格式。

3.3 编写技能代码：真正的“手艺活”

SKILL.md是说明书，skill.py是执行者。我写了一个简单的数据分析技能：

python复制import csv
import json
import statistics
from typing import Dict, Any

def analyze_csv(file_path: str, delimiter: str = ",") -> Dict[str, Any]:
    """
    Analyze a CSV file and return statistical summaries.
    """
    with open(file_path, newline="", encoding="utf-8") as f:
        reader = csv.DictReader(f, delimiter=delimiter)
        rows = [row for row in reader]

    if not rows:
        return {"error": "Empty CSV file"}

    columns = list(rows[0].keys())
    numeric_stats = {}
    categorical_stats = {}

    for col in columns:
        # try to parse column as numeric
        try:
            values = [float(row[col]) for row in rows if row[col] != ""]
            numeric_stats[col] = {
                "mean": statistics.mean(values),
                "median": statistics.median(values),
                "std": statistics.stdev(values) if len(values) > 1 else 0.0,
            }
        except (ValueError, TypeError):
            # treat as categorical
            value_counts = {}
            for row in rows:
                val = row[col]
                value_counts[val] = value_counts.get(val, 0) + 1
            categorical_stats[col] = value_counts

    result = {
        "columns": columns,
        "numeric_stats": numeric_stats,
        "categorical_stats": categorical_stats,
    }
    return result

if __name__ == "__main__":
    import sys
    path = sys.argv[1]
    print(json.dumps(analyze_csv(path), ensure_ascii=False, indent=2))

这段代码本身不复杂，但有几个细节值得说。第一，异常处理很重要——不是所有列都能转成数值，无法转换的列就自动归类为分类变量，这样模型拿到结果时不会因为某个字段缺数据而报错。第二，返回值必须是结构化的JSON，而且要符合SKILL.md中的约定。第三，主函数入口要支持命令行调用，方便调试也方便代理框架直接执行。

3.4 接入Semantic Kernel与AutoGen

技能写好了，怎么让代理真正用起来？微软生态里最简单的方式是Semantic Kernel。示例代码：

python复制from semantic_kernel import Kernel
from semantic_kernel.agents import AgentSkills

kernel = Kernel()
# 加载技能目录
await kernel.add_skill(parent_directory="./", skill_name="my-skill")

加载完成后，模型就能根据用户请求自动决定是否调用“my-skill”里的代码。这里有个我实际测试中发现的坑：Semantic Kernel加载技能时，默认会扫描目录下的所有子目录，如果目录里存在与技能同名的子目录或中间文件，可能导致加载失败。所以目录结构务必保持干净，一个技能对应一个文件夹，不要混放其他文件。

在AutoGen中使用类似，直接注册一个新工具函数即可：

python复制from autogen import ConversableAgent

analyzer_agent = ConversableAgent(
    "analyzer",
    system_message="You are a data analysis assistant. Use the analyze_csv skill when needed.",
    llm_config={"config_list": [...]},
)
analyzer_agent.register_for_llm(name="analyze_csv", description="Analyze a CSV file")(analyze_csv)

3.5 测试技能包：把Bug扼杀在“代理调用之前”

我把技能接入代理前，习惯先用一个独立脚本做一次冒烟测试。你可以直接用命令行跑：

bash复制python skill.py ./test.csv

然后人工检查输出结果是否符合预期。这一步看似多余，实则极重要——因为代理环境里的错误信息往往被吞掉，一旦技能代码本身有bug，你很难判断到底是代码问题还是模型调用参数有问题。先单独把技能调稳，再接进代理，能省下大量排查时间。

4. 实战进阶：Agent Skills × 本地模型，搭一套离线AI代理助手

4.1 为什么要把本地模型和Agent Skills绑在一起

前面讲的都是在线模型（GPT、Claude等）配合Agent Skills的场景。但我最近研究的重点其实是另一个方向：用本地模型（Llama 3.1 8B、Qwen2.5 14B等）搭配Agent Skills，搭一套完全离线运行的AI代理助手。这个需求来自一个很现实的场景——企业内部的敏感数据，或者个人电脑上的隐私文件，很多人其实不太放心直接丢给云端API处理。

在线模型的好处是推理能力强，但调用API意味着数据要离开本地机器。对很多公司来说，“数据不出域”是硬性要求；对个人用户来说，有些文件的内容实在不适合上传。所以“本地模型+Agent Skills”的组合就变得很有吸引力：模型在本地推理，技能在本地执行，数据从头到尾不出这台机器。

当然本地模型也有明显短板：指令遵循能力比GPT-4弱不少，复杂推理容易翻车。这正是Agent Skills能发挥价值的地方——技能包把任务的大部分逻辑固化在代码里，模型只需要输出“调用哪个技能、传什么参数”这个决策，而不需要自己在推理过程中生成完整步骤。换句话说，Agent Skills降低了本地模型的任务复杂度，让8B、14B量级的模型也能干漂亮的活。

4.2 本地模型工具调用能力实测：别指望它“自由发挥”

我先跑了一组实验，对比几款主流本地模型在“Agent Skills调用”场景下的表现。测试方法很简单：给定一个CSV分析任务，看模型能不能正确输出类似 {"skill": "analyze_csv", "parameters": {"file_path": "sales.csv"}} 这样的调用指令。

最直观的结论就是：本地模型的工具调用能力远不如GPT-4，但只要任务拆得足够细、SKILL.md写得足够清楚，它们还是能胜任一部分实际工作的。

我用Ollama拉起本地模型做个快速测试：

bash复制ollama run qwen2.5:14b

然后在Python里调用Ollama的API，要求模型输出结构化调用指令：

python复制import requests
import json

payload = {
    "model": "qwen2.5:14b",
    "messages": [
        {"role": "system", "content": "You are an AI assistant. You have access to a set of skills. When a user asks a task that matches a skill, respond with JSON in the format: {\"skill\": \"skill_name\", \"parameters\": {...}}"},
        {"role": "user", "content": "帮我分析一下sales.csv的统计数据"}
    ],
    "temperature": 0.0
}

response = requests.post("http://localhost:11434/api/chat", json=payload)
data = response.json()
print(data["message"]["content"])

我实测的结果是，Qwen2.5 14B在temperature设为0时不带随机性，输出基本稳定在JSON格式，偶尔会在JSON前后加多余的文字。解决办法也很粗暴：在SKILL.md的Example里加强格式约束，同时在后端解析时做一层容错，比如用正则把第一个{到最后一个}之间的内容截出来。

4.3 完整方案：本地模型作为“决策大脑”，Agent Skills作为“执行手脚”

我最后搭出来的离线代理助手结构是这样的：

text复制[用户输入]
   ↓
[路由模块]
   ↓
[本地模型(Qwen2.5 14B)]
   ↓ 输出结构化调用指令
[Agent Skills调度器]
   ↓
[技能包执行: analyze_csv, pdf_parser, sql_query, etc.]
   ↓
[结果返回给模型，格式化为自然语言回答]

这个流水线的关键在于把决策和执行彻底分离：模型只负责理解用户意图，然后从技能列表里挑一个合适的；真正干活的是技能包里的代码。这样设计的好处非常明显：本地模型不需要具备强大的推理规划能力，只需要做好“意图识别+参数提取”这两件事。事实证明，14B模型干这两件事已经足够好。

在调度器里，我用了一个很简单的匹配逻辑：根据用户输入和每个技能的Description做关键词/语义匹配。如果你的技能较多，可以用向量数据库做更精确的检索，但技能数量在二十个以内时，基于关键词+规则的方式完全够用，而且更可控。

调度器核心代码：

python复制def dispatch(user_input: str, skills: dict):
    """
    Simple dispatcher: match skill description against user input.
    """
    best_skill = None
    best_score = 0
    for name, skill in skills.items():
        score = compute_overlap(user_input, skill["description"])
        if score > best_score:
            best_score = score
            best_skill = name
    return best_skill

4.4 实测效果与性能数据

整套方案跑下来，我用了一个包含员工信息、销售记录和产品分类的CSV数据集（约2000行），测试了三类常见任务：

第一类“描述性统计”，比如“计算所有产品的平均价格”。本地模型识别技能、提取参数、调用代码，整个过程大约5秒（在Apple M2上，模型推理大概占3秒，代码执行不到1秒），结果完全正确。

第二类“条件统计”，比如“统计华东区上个月的销售额总和”。这个任务稍微复杂，Qwen2.5偶尔会把日期条件漏掉，导致统计结果不对。后来我在SKILL.md里增加了“必须严格包含所有筛选条件”的提示，并对调度器做了参数补全校验，准确率从70%左右提升到了90%以上。

第三类“跨技能组合”，比如“先读取PDF里的表格数据，再分析统计规律”。这个对本地模型来说是最难的，因为涉及两个技能的顺序编排。实测中小模型经常只调用第一个技能，忽略了第二个。我的临时解决办法是在路由层加了一个“任务步骤拆分”环节，让模型先输出步骤序列，再去逐个执行技能。效果有提升，但离完美还很远，这算是当前本地模型方案的天然瓶颈。

5. 这套方案踩过的坑与独家排查技巧

5.1 本地模型输出格式不稳定的“三板斧”解法

用过本地模型做工具调用的朋友应该都有这个体会：小模型的输出经常不合规，要么多了前缀后缀，要么漏掉参数，要么把JSON格式写坏。我试过不少方法，最后沉淀出三板斧：

第一，把temperature设为0，这是最基础也是最有效的一招。对工具调用这种确定性任务，随机性越少越好。第二，在SKILL.md里写清楚“你只能输出JSON，不要输出任何其他内容”，配合一个标注好的Example。第三，在代码层做兜底解析：用正则从模型输出中提取JSON块，再强制类型转换，不缺参数就继续执行。

这三板斧组合起来，能让Qwen2.5 14B的调用成功率稳定在90%以上。模板解析代码：

python复制import re
import json

def extract_json(raw_output: str):
    """
    Extract JSON object from model output with robust parsing.
    """
    # remove markdown code fences
    raw_output = re.sub(r"```(?:json)?", "", raw_output).strip()
    start = raw_output.find("{")
    end = raw_output.rfind("}")
    if start == -1 or end == -1:
        return None
    json_str = raw_output[start:end+1]
    try:
        return json.loads(json_str)
    except json.JSONDecodeError:
        # attempt to fix common issues: trailing commas
        json_str = re.sub(r",\s*([}\]])", r"\1", json_str)
        return json.loads(json_str)

5.2 SKILL.md写不好，模型永远用不对技能

我在实验中发现一个特别明显的现象：同样一个技能，SKILL.md写得好不好，直接决定本地模型能不能正确调用。一开始我把技能描述写得特别详细，恨不得把实现原理都写进去，结果模型反而被冗长的信息干扰，经常在参数上出错。后来我按“少即是多”的原则重写，Description控制在一两句话，Parameters只列必需的，Example给一个但不贪多，效果立竿见影。

这里有个小技巧：写Description时，不要只写“这个技能可以分析CSV”，而要写清楚“当用户请求涉及表格数据统计时使用”，也就是反向描述触发条件。本地模型对“什么时候用”比“怎么用”更敏感。

5.3 技能包加载失败与依赖冲突排查

Semantic Kernel加载技能包时，有几次报错都跟依赖有关。比如技能要用的pandas版本和环境里已有的版本冲突，或者在requirements.txt中声明了但没真正安装。我的习惯是每个技能用一个独立的虚拟环境，或者在主环境里统一安装并固定版本号，避免“在我这能跑、在别人那跑不了”的问题。另外加载技能的路径尽量用绝对路径，相对路径在项目结构变化时会莫名其妙找不到文件。

还有一个容易忽略的坑：技能目录名不要用中文或空格。Semantic Kernel对目录名的解析有时候会有问题，我第一次试的时候用了个带空格的目录名，加载直接失败，改成下划线就好了。这类问题排查起来特别隐蔽，因为报错信息往往很笼统。

5.4 如何判断“这个任务该不该交给本地模型”

这个可能是最容易被忽视的问题。本地模型+Agent Skills这套方案再香，也不是万能的。我现在的判断标准很简单：如果任务的核心逻辑可以被代码完全覆盖，只是需要模型做意图识别和参数提取，就可以用本地模型；如果任务需要模型自己生成内容、自主规划多步推理，那本地模型就不太行，还得上云端大模型。

打个比方，Agent Skills把AI代理里的“肌肉记忆”都固化了，但“临场发挥”的部分还是得靠大模型本身。所以我的建议是：能用代码解决的逻辑，尽量写进技能包里；模型只需要做它最擅长的“理解+调用”即可。这是这套组合架构能够落地的核心原则。

6. 扩展思考：Agent Skills还能怎么玩

除了离线场景，Agent Skills在其他方向上也有不少想象空间。比如团队内部的知识库问答：把文档解析、向量检索的技能打包成一个Agent Skill，配合本地模型就能在企业内部搭一个不依赖外部API的知识助手。再比如自动化报表生成：一个技能负责连数据库，一个技能负责渲染Excel图表，一个技能负责发送邮件，三个技能串起来就是一个完整的报表流水线。

微软把Agent Skills定位为Agent Framework的一部分，但它背后的思想其实通用。无论你用的是Semantic Kernel、AutoGen还是LangGraph，都可以借鉴“技能描述+代码实现+输入输出规范”这个三层结构来组织你的代理能力。我在自己的多个项目里已经开始用这套思路重构原来的工具调用代码，代码复用率显著提升，维护成本也降下来了。

最后再分享一个小技巧：写技能包的时候，顺手在SKILL.md里写一句“这个技能的局限”或者“出错时该怎么办”，模型遇到边界情况时会更从容，不会硬着头皮乱调用。这个细节是我在多次实测后加上的，确实减少了“模型拿技能硬凑结果”的情况。如果你也在折腾AI代理，强烈建议从写一个最小的技能包开始，亲手试试看。