【大模型】告别LLM幻觉：Agent Skills 底层机制与开发指南

SavEMyselF1

898人浏览 · 2026-03-09 12:33:30

SavEMyselF1 · 2026-03-09 12:33:30 发布

哈喽，各位开发者！在 AI 应用落地的过程中，大家一定都吃过大模型“幻觉”和“自由发挥”的苦。让 Agent 导出一份报表，它今天给你 Markdown，明天给你弄个 HTML，极度不可控。

为了解决这个问题，Anthropic 在 2025 年推出了 Agent Skills（智能体技能）。简单来说，Skills 就是一种模块化的能力扩展系统。它把你针对某个特定任务写好的指令（Prompt）、参考文档和执行脚本打包成一个可重用的单元。Agent 一旦装备了这个 Skill，就会严格按照你定的 SOP（标准作业程序）去干活。

既然知道了 Skills 能让 Agent 变得像熟练工一样靠谱，那它底层到底是如何高效运作的呢？这就不得不提它极其优雅的加载机制了。

一、核心架构：三层渐进式加载

以前我们为了约束 AI，会把几万字的背景设定全塞进系统提示词里，这不仅极其消耗 Token，还会导致严重的上下文污染。Skills 为了解决这个问题，采用了渐进式披露 (Progressive Disclosure) 的三层架构：

发现阶段 (Discovery)： Agent 启动时，绝对不会把所有的技能代码和长文档都读进内存。它只会轻量级地加载每个可用技能的名称 (name) 和描述 (description)，相当于只看一眼“技能菜单”。
激活阶段 (Activation)： 当用户的提问与菜单上的某个描述精准匹配时，Agent 才会把该技能的完整说明书（SKILL.md）加载到上下文中，仔细阅读具体的操作步骤。
执行阶段 (Execution)： 在执行具体任务时，Agent 会根据说明书的指引，按需调用底层脚本（如 Python 代码）或读取参考文档，真正开始处理数据。

了解了底层的高效加载机制，我们来看看在实际开发中，一个工业级的 Skill 长什么样。它有着非常严格的目录规范。

二、目录结构与核心组件

一个标准的 Skill，在文件系统中必须保持如下的拓扑结构：

my-skill-name/            # 技能根目录
├── SKILL.md              # [必填] 技能大脑：包含元数据与主指令
├── scripts/              # [可选] 动作库：存放 Python/Bash 等可执行代码
├── references/           # [可选] 知识库：存放长篇的 API 参考或业务规范文档
└── assets/               # [可选] 资源库：存放模板、静态图片等

在这个目录树中，绝对的核心就是 SKILL.md。我们可以把它拆开来仔细研究一下。

剖析 SKILL.md

这个文件由两部分组成：顶部的 YAML 元数据 和下方的 Markdown 正文。

1. YAML 元数据（给 Agent 的路由引擎看） 必须写在文件最开头，用 --- 包裹。

name：限制 64 字符内，只能用小写字母、数字和连字符。
description：限制 1024 字符内。这是 Agent 决定是否使用该技能的唯一判断标准，必须精准描述使用场景！

2. Markdown 正文（给 Agent 的大脑看） 这里是你编写 SOP 的地方。强烈建议采用结构化写法，包含：工作目标、分步执行流程、输入输出格式要求，以及遇到错误时的兜底方案。

光说理论不够直观，接下来我们直接动手。

三、开发 `csv-analyzer` 技能

我们要开发一个名为 csv-analyzer 的技能，目标是让 Agent 能够安全、规范地读取本地 CSV 文件，并输出统计摘要，而不是让它自己瞎写代码去解析。

1. 创建项目结构

在你的电脑上新建如下文件夹和文件：

csv-analyzer/
├── SKILL.md
└── scripts/
    └── analyzer.py

2. 编写 SKILL.md (指令中心)

将以下内容复制进 csv-analyzer/SKILL.md 中：

---
name: csv-analyzer
description: Read, clean, and analyze local CSV datasets. Trigger this skill ONLY when the user provides a CSV file path and asks for data analysis, profiling, or summary statistics.
license: Apache-2.0
---

# CSV Data Analysis Workflow

## Objective
Provide accurate data profiling for local CSV files by strictly executing the provided Python script. Do not write your own pandas code.

## Execution Steps
1. **Validate Input:** Check if the user has provided a valid path to a `.csv` file.
2. **Execute Script:** Run the python script located at `scripts/analyzer.py`, passing the CSV file path as the first argument.
3. **Format Output:** The script will output a JSON string. Parse this JSON and present the findings to the user using a clean Markdown table.

## Edge Cases
- If the script returns an error (e.g., file not found), politely inform the user and ask them to verify the file path.

3. 编写执行脚本 (底层引擎)

将以下内容复制进 csv-analyzer/scripts/analyzer.py 中。这部分代码负责真正干活，并将结果通过标准输出流（stdout）返回给 Agent。

import sys
import os
import json

def process_csv(file_path):
    # 1. 基础的边界校验
    if not os.path.exists(file_path):
        print(json.dumps({"status": "error", "message": "File not found."}))
        sys.exit(1)
        
    try:
        # 2. 核心处理逻辑（此处为演示，仅做基础的行数和表头读取）
        with open(file_path, 'r', encoding='utf-8') as f:
            lines = f.readlines()
            
        row_count = len(lines) - 1 if len(lines) > 0 else 0
        columns = lines[0].strip().split(',') if row_count >= 0 else []
        
        # 3. 封装结构化数据
        result = {
            "status": "success",
            "data": {
                "file_name": os.path.basename(file_path),
                "total_rows": row_count,
                "columns": columns,
                "summary": "Data successfully loaded for profiling."
            }
        }
        
        # 4. 打印 JSON，Agent 会自动捕获这段输出
        print(json.dumps(result))
        sys.exit(0)
        
    except Exception as e:
        print(json.dumps({"status": "error", "message": str(e)}))
        sys.exit(1)

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print(json.dumps({"status": "error", "message": "Missing file path argument."}))
        sys.exit(1)
        
    target_csv = sys.argv[1]
    process_csv(target_csv)

4. 操作说明与运行验证

准备测试数据： 在 csv-analyzer 目录外，随便建一个 data.csv，写几行测试数据（比如 id,name,age\n1,Tom,20）。
挂载技能： 将包含 csv-analyzer 的父目录配置到你的 Agent 开发环境（如 Claude Code 或其他兼容 Anthropic Skills 的 IDE）的加载路径中。
对话触发： 在对话框对 Agent 说：“帮我分析一下桌面的 data.csv 文件。”
见证奇迹： 你会看到 Agent 瞬间领悟意图，不再胡乱生成代码，而是精准调用了你写的 analyzer.py，并将底层返回的 JSON 优雅地转换成了 Markdown 表格展示给你。

代码跑通了，看着 Agent 乖乖按你的脚本干活是不是很爽？但别高兴得太早，在企业级生产环境中，安全防御永远是重中之重。

既然开放了脚本执行权限，就等于把服务器的半个后门交给了 AI。以下三大红线必须防范：

防御提示词注入 (Prompt Injection)： 永远不要信任用户的输入。如果在脚本中需要拼接系统命令（如 os.system()），必须做极其严格的过滤，防止用户通过输入恶意文件名（如 test.csv; rm -rf /）引发远程代码执行。
环境沙盒化： scripts/ 下的代码绝对不能在宿主机的 Root 权限下裸奔，建议通过 Docker 容器或沙盒环境限制其文件读写范围。
网络出站控制： 严防数据外泄。除了明确需要调用外部 API 的技能，其他本地处理类技能的脚本，应当通过防火墙阻断其访问外网的能力。

ok，经过上面的讲述，你已经了解skills了吧，把你的skills上传到Claude code和cursor等AI应用来尝试一下吧。