在 Genkit Go 中借助 Agent Skills 按需启用专家能力

2026 年 7 月 31 日　　Daniela Petruzalek　资深开发者关系工程师　　分享

基于大语言模型的智能体（agent）正越来越多地被用于自动化复杂的工作流。然而，随着其职责不断扩展，如何管理提示词上下文（prompt context）的体量成为一项挑战。将所有标准操作流程、参考指南和文档一股脑地加载到持久化上下文窗口中并不可持续：它会消耗宝贵的 token，稀释模型的注意力，并增加模型产生错误回答的概率。

为了解决这一问题，我们在面向 TypeScript、Go、Dart 和 Python 的 Genkit 中新增了对 Agent Skills 的支持。本文将演示如何在 Genkit Go 中使用 Agent Skills。Agent Skills 标准允许开发者将专业领域的专家知识打包成可被发现的（discoverable）能力，仅在需要时才由智能体加载。它们相当于一组专门的知识包，平时安静地待在后台，直到真正需要的那一刻才会浮出水面。

Agent Skills 简要回顾

Agent Skills 遵循一种被称为渐进式披露（progressive disclosure）的原则：信息只有在必要时才会被揭示给模型。每个技能（skill）通过一个 SKILL.md 文件来定义，该文件包含两部分：前置元数据（frontmatter）和正文（body）。前置元数据中包含技能描述以及其他元数据信息；正文部分则承载实际交给模型执行的指令。此外，还可以附带诸如参考文件或脚本之类的补充文件。

依据该规范，一个技能在磁盘上的组织结构如下所示：

skill-name/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行代码
├── references/       # 可选：参考文档
├── assets/           # 可选：模板、资源
└── ...               # 任意其他文件或目录

下面是一段技能前置元数据的示例：

---
name: adr-template
description: 在提出重大架构变更、记录代码库重构，或解决设计/技术争议时激活此技能。使用该技能编写并维护架构决策记录（ADR），以保留工程上下文。
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

最初，智能体运行框架（agent harness）会从 SKILL.md 文件中加载技能定义，但仅将其前置元数据暴露给智能体的系统提示。这些信息足以让模型判断是否需要激活该技能。随着对话的推进，当出现该技能可能适用的情境时，激活流程便会启动，并将技能的完整正文加载进来。根据正文内容，模型还可能决定进一步加载附加的参考资料或调用打包好的脚本，从而完成针对该任务的整个披露循环。

这一流程可由下图概括：

progressive-disclosure

借助渐进式披露，token 的消耗会被推迟到真正必要时才发生。示意图由 Gemini 3.1 Flash Image 生成。

这种渐进式披露模式带来三大核心优势：

Token 利用率高：Genkit 初始时仅加载技能的元数据，仅当技能被激活后才注入详细指令。
实现轻量：技能本质上是一组 Markdown 文件，可以像代码一样分发。无需配置任何额外的基础设施即可享受技能带来的便利。
资源可打包：技能内部可以携带自己的脚本（Python、Node.js、Bash 等），由智能体按需执行，从而确保模型手边始终拥有恰到好处的工具。

Genkit Go 中的 Agent Skills

要理解 Agent Skills 在 Genkit Go 中的运作方式，我们首先需要了解 Genkit 中间件架构。Genkit 中间件相当于一组钩子（hook）构成的流水线，用于拦截并包裹模型生命周期的关键阶段：

模型包装器（WrapModel）：在一次迭代中的每次模型 API 调用时触发，处理与模型调用本身相关的逻辑，例如重试、回退（fallback）和缓存。
工具包装器（WrapTool）：在每次工具执行时触发；同一迭代中的并行工具调用可并发运行。
生成包装器（WrapGenerate）：在每次工具循环迭代中触发（若包含 N 轮工具调用，则触发 N+1 次），用于处理需要纵观全局对话的逻辑，例如重写、系统提示注入以及消息累积。

Agent Skills 正是构建在这套钩子系统之上。中间件会监听传入的提示，一旦发现匹配的描述，便会动态激活相应技能。

下面的代码片段演示了如何为你的 Genkit 流程添加技能支持：

resp, err := genkit.Generate(ctx, g,
    ai.WithPrompt("How do I run tests in this repo?"),
    ai.WithUse(&middleware.Skills{SkillPaths: []string{"./skills"}}),
)

工作原理

技能的运用可划分为三个阶段：

发现（Discovery）：在使用技能中间件初始化 Genkit 时，系统会扫描你配置的 SkillPaths，查找其中的 SKILL.md 文件，并将其元数据注入系统提示。
激活（Activation）：当用户请求匹配上某个技能的描述时，Genkit 会调用 use_skill 工具来取回当前任务所需的特定指令。
执行（Execution）：SKILL.md 文件的完整内容，连同其中打包的资源（例如脚本和参考文件）的访问方式，会一并被加载到当前上下文中，以引导模型精准地完成既定工作流。

环境准备

安装 SDK

要开始使用 Genkit 中的 Agent Skills，请首先确保你安装了最新版本的 Genkit Go SDK：

go get github.com/firebase/genkit/go

安装 Genkit CLI

该步骤可选，但推荐使用。在 macOS 或 Linux 上，运行：

curl -sL cli.genkit.dev | bash

在 Windows 上，请从以下地址下载二进制文件：cli.genkit.dev

更多细节可访问 https://cli.genkit.dev 获取。

向基础流程中添加技能

在安装好 SDK 之后，你便可以注册技能中间件，并在 Generate 调用时启用它。下面的代码示例定义了一个由 Genkit 流程驱动的命令行菜谱生成工具：

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/firebase/genkit/go/ai"
    "github.com/firebase/genkit/go/genkit"
    "github.com/firebase/genkit/go/plugins/googlegenai"
    "github.com/firebase/genkit/go/plugins/middleware"
    "google.golang.org/genai"
)

func main() {
    if len(os.Args) < 2 {
        fmt.Println("Usage: recipe <food|ingredient>")
        os.Exit(1)
    }

    input := os.Args[1]

    ctx := context.Background()

    g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}, &middleware.Middleware{}))

    recipeFlow := genkit.DefineFlow(g, "recipeFlow", func(ctx context.Context, input string) (string, error) {
        prompt := fmt.Sprintf("Provide a recipe using %s", input)

        return genkit.GenerateText(ctx, g,
            ai.WithModel(googlegenai.ModelRef("googleai/gemini-flash-latest", &genai.GenerateContentConfig{
                ThinkingConfig: &genai.ThinkingConfig{
                    ThinkingLevel: genai.ThinkingLevelLow,
                },
            })),
            ai.WithSystem(
                "You are a professional chef assistant with wide knowledge about recipes. "+
                    "The user will give you a food or ingredient and you need to respond with a recipe. "+
                    "Use specialized knowledge (skills) whenever possible. "+
                    "Respond with ASCII formatting optimized for terminal output (no markdown).",
            ),
            ai.WithPrompt(prompt),
            ai.WithUse(&middleware.Skills{SkillPaths: []string{"./skills"}}),
        )
    })

    result, err := recipeFlow.Run(ctx, input)
    if err != nil {
        log.Fatalf("Error running flow: %v", err)
    }

    fmt.Println(result)
}

请注意，我们通过 ai.WithUse 函数选项在 genkit.GenerateText 中配置了 Skills 中间件。在实例化的 Skills 中间件里，我们通过 SkillPaths 将 ./skills 目录映射进来；该目录在本例中包含两个技能：banana-bread 与 cheese-bread。

使用 cheese 作为参数运行程序，会激活 cheese-bread 技能，并返回相应的菜谱：


$ go run main.go cheese
+-------------------------------------------------------------+
|               TRADITIONAL BRAZILIAN CHEESE BREAD            |
|                        (Pao de Queijo)                      |
+-------------------------------------------------------------+

Naturally gluten-free, crispy on the outside, and chewy inside.

===============================================================
INGREDIENTS
===============================================================
* Tapioca Flour (Sour Starch) .. 2 cups (240g)
* Whole Milk .................. 1/2 cup (120ml)
* Water ....................... 1/2 cup (120ml)
* Vegetable Oil ............... 1/3 cup (80ml)
* Salt ........................ 1 tsp
* Eggs (Room Temp) ............ 2 large
* Grated Parmesan/Queijo ...... 1.5 cups (150g)

===============================================================
EQUIPMENT
===============================================================
* Medium saucepan
* Mixing bowl or Stand mixer with paddle attachment
* Baking sheet with parchment paper
* Ice cream scoop (optional)

===============================================================
INSTRUCTIONS
========================

Enable on-demand expertise with Agent Skills in Genkit Go

AI智能总结