blog

# tRPC-Agent-Go Skills：Anthropic Agent Skills 规范的 Go 原生实现

> tRPC-Agent-Go 框架第一时间支持了 Anthropic 风格的 Agent Skills。本文将从“如何使用”到“设计实现”依次展开，帮助你在实际业务中自如地启用和扩展这一能力。

> [tRPC-Agent-Go](https://github.com/trpc-group/trpc-agent-go/) 是面向 Go 语言的自主式多 Agent 框架，具有工具调用、会话与记忆管理、制品管理、多 Agent 协同、图编排、知识库与可观测等能力。tRPC-Agent-Go 的成长离不开大家的支持，欢迎 Star 项目。

在很多基于大语言模型（Large Language Model，LLM）的 Agent 项目里，真正的挑战并不只是“让模型变聪明”，而是如何把一整套任务知识沉淀成可复用的技能，用按需加载的方式喂给模型，并在受控环境中安全落地执行。Anthropic 提出的 Agent Skills 提供了一条很清晰的路径：把可复用的任务封装为技能目录，用 `SKILL.md` 描述目标与流程，用文档和脚本补充细节，由系统在对话过程中按需加载这些信息，并在工作区中完成实际操作。

tRPC-Agent-Go 在框架层对齐了这套设计：一方面提供 Skill 仓库存取、概览与正文注入等上下文能力，另一方面结合 Workspace 抽象，把技能涉及的脚本放进隔离工作区中安全运行，让“任务知识 + 文档 + 可选脚本”成为一个统一、可控的 Agent 能力层。

本文会从零开始，带你理解：
- Agent Skills 的整体思路和典型使用场景
- tRPC-Agent-Go 中如何按需加载 Skill 的上下文
- Skills 与执行环境结合后的能力边界
- 作为业务方，如何快速启用并扩展这一能力

后文会先梳理背景与概念，再给出一个最小使用示例，最后展开框架内部的设计与实现，帮助你把 Skill 看清楚、用得稳。

## 背景

### 传统痛点

在没有 Agent Skills 之前，我们通常这样给 LLM“加能力”：把一堆“操作手册”“命令示例”写在提示词里，再让模型按这些说明生成代码或操作步骤，由人类或外部系统去执行。

这种方式有两个明显问题：

1. 上下文爆炸：所有步骤、脚本都写在提示词里，上下文窗口（Context Window）被快速占满，成本高、可维护性差。  
2. 执行环境割裂：模型只“说”脚本，不真正“跑”脚本，执行结果需要人工搬运，难以形成闭环，也不利于审计和回溯。

Anthropic 在文章 [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) 中提出了一套统一的解决方案：把可复用的任务封装为 Skill 目录，用 `SKILL.md` 描述目标与流程，用文档和脚本补充细节，由系统管理技能的发现、加载和执行。开源仓库 [`anthropics/skills`](https://github.com/anthropics/skills) 中提供了大量示例 Skill，如 PDF 处理、PPT 生成等。

tRPC-Agent-Go 在设计 Skill 能力时，完全对齐了这套语义：`SKILL.md` 的格式和含义与 Anthropic 官方一致，技能目录结构也与上述示例仓库兼容，你可以直接把 Claude Skills 仓库指给 tRPC-Agent-Go 使用，而不需要改写 `SKILL.md`。

### 三层模型

先看一个极简的技能目录示例，帮助你对 Skill 的“长什么样”有一个直观印象。

```text
skills/
  report-summary/
    SKILL.md
    USAGE.md
    scripts/
      summarize.py
```

其中 `SKILL.md` 的内容可以非常简单，例如：

```markdown
---
name: report-summary
description: Summarize long reports into short bullet points.
---

Usage

- When the user asks to summarize a long report into a concise outline.

Steps

1) Read the input file from $WORK_DIR/inputs/report.txt
2) Run: python3 scripts/summarize.py > $OUTPUT_DIR/summary.txt
3) Return a short natural language summary and mention summary.txt
```

这个例子里：YAML 头部的 `name` 和 `description` 提供“概览”，正文部分给出了使用时机和具体步骤，`USAGE.md` 作为补充说明，`scripts/summarize.py` 则是实际执行的脚本。真正做到“用起来像一个技能”，靠的就是对这些内容按需加载和执行。

在 Anthropic 的 Agent Skills 规范中，一个 Skill 目录本质上包含三层信息：

```mermaid
flowchart LR
    A[概览层 name + description]:::overview --> B[正文层 SKILL.md body]:::body
    B --> C[文档与脚本层 docs + scripts]:::docs

    classDef overview fill:#e1f5e1,stroke:#4caf50,stroke-width:2px
    classDef body fill:#e3f2fd,stroke:#2196f3,stroke-width:2px
    classDef docs fill:#fff3e0,stroke:#ff9800,stroke-width:2px
```

1. 概览层：只包含 `SKILL.md` YAML 头部中的 `name` 和 `description`，成本极低，可以在每轮对话一开始就注入，用来告诉模型“有哪些技能、各自做什么”。  
2. 正文层：`SKILL.md` 的 Markdown 正文，描述“何时使用”“具体步骤”“命令示例”，只在模型决策“要用这个 Skill”时，通过工具调用按需加载。  
3. 文档与脚本层：附加的 Markdown 文档和脚本文件，文档按需选取一部分注入，脚本只在工作区执行，不会被原样放进提示词。

这个“三层模型”是理解 Agent Skills 的核心：Agent 只在需要时才把更“重”的信息拉进上下文或执行环境，从而在“能力强”和“成本低”之间取得平衡。

## 快速开始

本节从“怎么用”出发，给出一个最小可运行示例，帮助你快速感受 tRPC-Agent-Go 的 Agent Skills 能力。

### 环境准备

- Go 1.21+  
- 一个 OpenAI 兼容模型服务的 Key  
- 一个 Skills 目录（可以直接使用示例目录 [`examples/skillrun/skills`](https://github.com/trpc-group/trpc-agent-go/tree/main/examples/skillrun/skills)）

常用环境变量：

```bash
export OPENAI_API_KEY="your-api-key"
export SKILLS_ROOT=/path/to/your/skills   # 可选，默认使用 ./skills
```

### 入门示例

下面这段代码是简化版的技能对话示例，基于 [`examples/skillrun/main.go`](https://github.com/trpc-group/trpc-agent-go/tree/main/examples/skillrun/main.go)。

```go
package main

import (
    "trpc.group/trpc-go/trpc-agent-go/agent/llmagent"
    "trpc.group/trpc-go/trpc-agent-go/codeexecutor/local"
    "trpc.group/trpc-go/trpc-agent-go/model"
    "trpc.group/trpc-go/trpc-agent-go/model/openai"
    "trpc.group/trpc-go/trpc-agent-go/runner"
    "trpc.group/trpc-go/trpc-agent-go/skill"
)

func main() {
    mdl := openai.New("gpt-4o-mini")

    repo, _ := skill.NewFSRepository("./skills")
    exec := local.New()

    agent := llmagent.New(
        "skills-assistant",
        llmagent.WithModel(mdl),
        llmagent.WithSkills(repo),
        llmagent.WithCodeExecutor(exec),
    )

    r := runner.NewRunner("demo-app", agent)
    ch, _ := r.Run(
        context.Background(),
        "user1", "session1",
        model.NewUserMessage("请用合适的 Skill 总结一个文本文件"),
    )

    for ev := range ch {
        // 处理流式响应与工具调用，这里略去细节。
        _ = ev
    }
}
```

这段代码做了几件事：用 `WithSkills(repo)` 打开 Agent Skills 能力，用 `WithCodeExecutor(exec)` 接入执行环境，并通过 `Runner` 发起一次对话，让模型可以在需要时自动选择并调用技能相关工具。

在实际对话中，一个典型流程大致是：模型先通过概览了解有哪些技能，当你说“用某个 Skill 做 X”或描述一个技能适用的任务时，它调用技能工具加载正文与文档，然后在技能工作区中执行命令并返回结果或输出文件。

后续章节会从实现角度解释：这些行为在框架内部是如何串起来的。

## 架构总览

先看一张总览图，帮助你把几个关键模块对上号：

```mermaid
flowchart TB
    subgraph "对话入口"
        U[用户消息]:::user
        R[Runner]:::runner
    end

    subgraph "LLMAgent 层"
        LA[LLMAgent WithSkills + WithCodeExecutor]:::agent
        PR[SkillsRequestProcessor 请求预处理]:::proc
        TLoad[skill_load 等工具]:::tool
        TRun[skill_run 工具]:::tool
    end

    subgraph "Skills 仓库"
        REPO[skill.Repository FSRepository]:::repo
        FS[技能目录 + SKILL.md]:::fs
    end

    subgraph "执行层（codeexecutor）"
        ENG[Engine]:::exec
        LRT[local.Runtime]:::rt
        CRT[container.workspaceRuntime]:::rt
    end

    U --> R --> LA
    LA --> PR
    PR --> LA
    LA -->|工具调用| TLoad
    LA -->|工具调用| TRun
    TLoad --> REPO
    TRun --> REPO
    TRun --> ENG
    ENG --> LRT
    ENG --> CRT
    REPO --> FS

    classDef user fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    classDef runner fill:#e8f5e9,stroke:#43a047,stroke-width:2px
    classDef agent fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    classDef proc fill:#fce4ec,stroke:#d81b60,stroke-width:2px
    classDef tool fill:#ede7f6,stroke:#5e35b1,stroke-width:2px
    classDef repo fill:#f1f8e9,stroke:#7cb342,stroke-width:2px
    classDef fs fill:#efebe9,stroke:#6d4c41,stroke-width:2px