让代理的上下文保持精简，同时不牺牲专业性。⚡ 了解 Genkit Go 中的 Agent Skills 如何将专业知识打包成按需加载的能力，帮助减少 token 用量，同时让 AI 代理更可靠。开始使用 →

使用 Genkit Go 中的 Agent Skills 实现按需专业知识

来源：https://developers.googleblog.com/enable-on-demand-expertise-with-agent-skills-in-genkit-go/

基于大型语言模型的代理（agent）越来越多地被用于自动化复杂工作流。然而，随着其职责的增长，管理提示（prompt）上下文的大小成为一项挑战。将每个标准操作流程、参考指南和文档都加载到持久上下文窗口中是不可持续的：这会消耗宝贵的 token，分散模型的注意力，并增加错误响应的可能性。

为了解决这个问题，我们在 Genkit 中为 TypeScript、Go、Dart 和 Python 添加了 Agent Skills（https://agentskills.io/）支持。本文将演示如何在 Go 中使用 Genkit 的 Agent Skills。

Agent skills 标准允许开发者将专业知识打包成可发现的能力，代理仅在需要时加载这些能力。它们就像专门的知识包，在需要之前一直停留在后台。

Agent Skills 简要回顾

Agent skills 遵循一种称为渐进式披露的原则，这意味着信息只有在必要时才会向模型展现。技能使用 SKILL.md 文件定义，该文件包含两个部分：frontmatter（前置元数据）和 body（正文）。frontmatter 包含技能描述和任何附加元数据。技能的正文本体是包含给模型的实际指令的部分。此外，还可以添加补充文件，例如参考资料或脚本。

根据规范（https://agentskills.io/home#what-are-agent-skills），技能在磁盘上的组织结构如下：

skill-name/
├── SKILL.md        # Required: metadata + instructions
├── scripts/        # Optional: executable code
├── references/     # Optional: documentation
├── assets/         # Optional: templates, resources
└── ...             # Any additional files or directories

以下是一个技能 frontmatter 示例：

---
name: adr-template
description: Activate this skill when proposing significant architectural changes, documenting codebase refactorings, or resolving design/technical debates. Use this skill to author and maintain Architecture Decision Records (ADRs) to preserve engineering context.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

起初，代理框架会从 SKILL.md 文件加载技能定义，但只将 frontmatter 暴露给代理的系统提示。这是代理判断是否必须激活该技能所需的信息。随着对话的推进，代理最终会遇到可能需要该技能的场景，这时激活过程将开始，加载技能的完整正文。根据正文内容，代理可能会决定加载额外的参考资料或使用捆绑的脚本，从而完成该任务的披露周期。以下图表总结了这一流程：progressive-disclosure

通过渐进式披露，token 消耗会被延迟到绝对必要时。图表由 Gemini 3.1 Flash Image 生成。

这种渐进式披露模型提供了三个关键优势：

• Token 效率：Genkit 最初仅加载技能的元数据，只有在技能激活时才注入详细指令。
• 轻量实现：技能是一组 markdown 文件，可以像代码一样分发。无需配置任何额外基础设施即可受益于技能。
• 资源捆绑：技能可以包含自己的脚本（Python、Node.js、Bash），代理可以执行这些脚本，确保其拥有完成任务所需的准确工具。

Genkit Go 中的 Agent Skills

要理解 Agent Skills 如何在 Genkit Go 中运行，我们必须首先了解 Genkit 中间件（https://developers.googleblog.com/announcing-genkit-middleware-intercept-extend-and-harden-your-agentic-apps/）架构。Genkit 中间件充当一个钩子管道，用于拦截并包装关键的模型生命周期阶段：

1. 模型包装器（WrapModel）：在每次迭代中，每个模型 API 调用触发一次，处理与模型调用本身相关的逻辑，例如重试、回退和缓存。
2. 工具包装器（WrapTool）：每次工具执行触发一次，可能在同一次迭代中为并行工具调用并发运行。
3. 生成包装器（WrapGenerate）：每次工具循环迭代触发一次（N 次工具轮次意味着 N+1 次调用），处理需要查看整个对话的逻辑，例如重写、系统提示注入和消息累积。

Agent Skills 构建在此钩子系统之上。通过监控传入的提示，中间件检测匹配的描述并动态激活技能。

以下代码片段演示了如何为 Genkit flow 添加技能支持：

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

工作原理

技能的使用分为三个不同阶段：

1. 发现：当使用技能中间件初始化 Genkit 时，系统会扫描你配置的 SkillPaths 中的 SKILL.md 文件，并将其元数据注入到系统提示中。
2. 激活：当用户请求与技能描述匹配时，Genkit 调用 use_skill 工具来检索当前任务所需的具体指令。
3. 执行：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://storage.googleapis.com/genkit-assets-cli/prod/win32-x64/latest.exe）

更多详情请访问 https://cli.genkit.dev/

向基本 flow 添加技能

安装 SDK 后，你可以注册技能中间件并在 Generate 调用期间提供它。以下代码示例定义了一个由 Genkit flow 驱动的配方生成命令行工具：

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 <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)
}

请注意，我们在 genkit.GenerateText 中使用 ai.WithUse 功能选项配置 Skills 中间件。在实例化的 Skills 中间件中，我们通过 SkillPaths 映射 ./skills 文件夹，该文件夹在此示例中包含两个技能：“banana-bread”和“cheese-bread”。

使用单词“cheese”运行应用程序会激活“cheese-bread”技能并返回相应的配方：

+-------------------------------------------------------------+
|                     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