1. 项目缘起与核心思路

最近在折腾一个挺有意思的东西，就是给AI写代码助手（比如Claude Code，也就是大家常说的Cline）开发一个“技能”（Skill）。这个技能的名字叫 skill-write-agent-use-adk-go ，顾名思义，它的核心任务就是指导AI如何用 adk-go 这个框架来编写Agent Skill。听起来有点绕？简单说，就是我想让AI学会“如何教别人用某个特定工具写程序”，而我这个项目本身，就是那个“教学大纲”和“示范案例”。

为什么会有这个想法？在深度使用Cline这类AI编程助手的过程中，我发现它们虽然能根据自然语言描述生成代码，但在面对一些特定框架、有固定范式或复杂约定的开发任务时，生成的代码往往需要大量人工调整。比如 adk-go ，它是一个用于构建AI Agent的开发套件，有自己的一套接口定义、生命周期管理和配置规范。如果每次开发新Skill，我都要手动给Cline解释一遍这些规则，效率太低，而且容易出错。于是我就想，能不能把对 adk-go 框架的理解、最佳实践和常见模式，封装成一个Cline能直接理解和执行的“技能包”？这样，以后我或者团队里其他人想用 adk-go 写新Agent，只需要告诉Cline“用那个写adk-go skill的技能”，它就能生成更规范、更符合框架预期的代码，大大提升开发效率和代码质量。

这个思路的核心价值在于 “元编程” 或者说 “让工具变得更智能” 。我们不再仅仅是使用AI来写代码，而是教AI如何更好地写某一类特定代码。这有点像给木匠打造一套更称手的、专门用于雕刻特定花纹的凿子。我的这个Skill，就是为Cline打造的，专门用于雕刻 adk-go 风格Agent的那把“凿子”。

2. 开发流程全解析：从构思到实现

我的整个开发流程非常直接，甚至可以说有点“取巧”，但恰恰体现了在AI辅助下，开发范式的一种转变。整个过程可以概括为： “先定义规则，再让AI执行规则” 。

2.1 第一步：撰写“宪法”—— 说明.md

我没有一上来就写代码，而是先创建了一个名为 说明.md 的文件。这个文件就是整个Skill的“宪法”或“设计说明书”。它的内容决定了最终生成的Skill是什么样子、能做什么。在这个文件里，我主要明确了以下几件事：

  1. 技能的身份与目标 ：开宗明义，说明这个技能是“adk-go-agent-skill”，它的核心目标是指导AI（特指Cline）如何编写基于adk-go框架的Agent Skill。这相当于设定了技能的“人设”和“任务”。
  2. 输入与输出规范 ：描述了技能应该接受什么样的用户请求（例如，“帮我写一个处理订单的Agent”），以及它应该输出什么（例如，一个完整的、符合adk-go项目结构的Go语言代码目录）。
  3. 核心逻辑与步骤 ：拆解了编写一个adk-go Skill的标准流程。这通常包括：
    • 项目初始化 ：创建标准的Go module，引入 adk-go 依赖。
    • 定义Agent结构 ：说明如何定义一个结构体，并嵌入 adk.Agent 基类，以及如何添加必要的字段。
    • 实现关键接口 ：详细说明必须实现的几个核心方法，比如 Initialize , Process 等，每个方法的签名、职责、返回值以及常见的实现模式是什么。
    • 配置处理 ：如何定义和使用配置文件（如YAML），如何将配置绑定到Agent的字段上。
    • 工具（Tools）集成 ：如果需要让Agent调用外部API或执行特定操作，如何定义和使用 adk-go 的Tool系统。
    • 测试与运行 ：提供简单的示例，说明如何编写单元测试，以及如何运行这个Agent。
  4. 代码风格与最佳实践 ：约定代码的格式（如使用gofmt）、错误处理的方式（优先返回error）、日志记录的标准（使用框架提供的logger）等。这部分确保了生成的代码不仅能用，而且“好看”、可维护。
  5. 示例模板 ：提供了一个最简化的、可运行的adk-go Agent代码模板。这个模板是技能生成代码的“蓝本”，AI会在其基础上根据用户的具体需求进行填充和修改。

实操心得 ：写这个 说明.md 的过程，其实就是把你脑中关于“如何正确做这件事”的所有隐性知识显性化、结构化的过程。它迫使你思考框架的边界、开发的步骤和可能遇到的坑。这份文档的质量，直接决定了最终AI生成技能的质量。写得越清晰、越具体、越具有可操作性，AI“学”得就越好。

2.2 第二步：召唤“工匠”——使用skill-creator

写好“宪法”之后，接下来的工作就交给AI了。我使用了另一个现成的Skill—— skill-creator 。顾名思义，这个Skill的专长就是“创建Skill”。

我的操作非常简单，在项目根目录下，直接给Cline输入了这样一条Prompt：

用skill-creator这个skill，根据@/说明.md 在当前目录完成一个skill

这条指令包含了几个关键信息：

  • 动作 ： 用...这个skill 。明确告诉Cline我要使用哪个工具。
  • 工具 ： skill-creator 。指定了执行创建任务的具体技能。
  • 依据 ： 根据@/说明.md 。 @ 符号通常是Cline中引用项目内文件的语法。这里将我们上一步精心编写的“宪法”文件作为输入源。
  • 目标 ： 在当前目录完成一个skill 。指明了产出物的位置和类型。

发出指令后， skill-creator 这个技能就被激活了。它会读取 说明.md 的内容，理解其中定义的技能规格、逻辑和模板，然后自动生成实现这些逻辑所需的全部代码文件，包括入口文件、逻辑处理文件、配置文件等等，并将它们组织成 adk-go 框架下一个标准Skill应有的结构。

2.3 第三步：验收与微调

AI生成代码并非一劳永逸。生成完成后，我需要扮演“质检员”的角色。

  1. 结构检查 ：首先看生成的项目目录结构是否正确，是否包含了 main.go 、 skill.yaml 、 go.mod 等必要文件。
  2. 代码逻辑审查 ：仔细阅读核心的Go代码，尤其是那些根据 说明.md 中“核心逻辑”部分生成的代码。检查接口实现是否正确，逻辑流程是否清晰，是否有明显的语法或逻辑错误。
  3. 功能测试 ：尝试在本地运行这个新生成的Skill。由于它是一个“指导写代码”的Skill，我可以模拟一个用户请求，比如“创建一个天气查询Agent”，看它能否生成一份基本可用的Go代码草案。
  4. 迭代优化 ：如果测试中发现生成结果与预期有偏差，比如某些细节处理不到位，或者 说明.md 中有描述不清的地方，我会回过头去修改 说明.md ，然后再次使用 skill-creator 生成，或者直接在生成的代码上进行手动调整。这是一个循环迭代的过程，直到Skill的表现稳定且符合要求。

注意事项 ：完全依赖AI生成而不加审查是危险的。AI可能误解你的描述，也可能采用一种可行但并非最优的实现方式。特别是对于涉及框架特定约定、错误处理边界条件等细节，人工审查至关重要。我的经验是，把AI当成一个能力超强的初级工程师，它负责产出初稿和完成大部分模板化工作，而你作为资深工程师，负责架构设计（写 说明.md ）和代码评审。

3. 核心实现细节与ADK-Go框架浅析

要让这个“教AI写代码”的Skill真正有用，它自身必须深刻理解 adk-go 。下面我就拆解一下，在这个Skill的“宪法”（ 说明.md ）中，我是如何定义这些核心细节的，以及它们背后的原理。

3.1 Agent的基本骨架：结构体与嵌入

在 adk-go 中，一个Agent通常由一个结构体表示。这个结构体需要嵌入（Embed）框架提供的 adk.Agent 基类。这样做的好处是，你的Agent自动继承了基类所有的方法和属性，无需重复实现一些通用逻辑。

在我的 说明.md 中，我会给出这样的模板：

package main

import (
    "context"
    "fmt"
    "github.com/your-org/adk-go"
)

// MyAgent 实现了具体的业务逻辑
type MyAgent struct {
    adk.Agent // 嵌入基类，这是关键
    // 在这里添加你的自定义配置字段
    // 例如：APIKey string `yaml:"api_key"`
    // 例如：MaxRetries int `yaml:"max_retries"`
}

// NewMyAgent 是一个构造函数，用于创建Agent实例
func NewMyAgent() *MyAgent {
    return &MyAgent{
        Agent: adk.NewBaseAgent(), // 初始化基类
        // 初始化你的自定义字段
    }
}

为什么这么做？ 嵌入 adk.Agent 使得你的结构体天然满足了 adk-go 框架对Agent对象的类型要求。框架可以通过这个基类来管理Agent的生命周期、调用标准接口。自定义字段则用于通过YAML配置注入，实现业务参数的可配置化。

3.2 生命周期的掌控：必须实现的接口

adk-go 框架通过几个核心接口方法来管理Agent的生命周期。我的Skill必须指导AI正确实现它们。

  1. Initialize(ctx context.Context) error

    • 职责 ：初始化Agent。在这里，你应该解析配置、建立数据库连接、初始化第三方SDK客户端等。这个方法在Agent启动后、处理任何请求之前调用，且只调用一次。
    • 实现要点 ：从 a.Config() 方法中获取配置映射，并将其绑定到你的自定义字段上。所有可能失败的操作（如网络连接）都应在此进行，并返回 error。框架会捕获这个error，如果初始化失败，Agent将无法启动。
    func (a *MyAgent) Initialize(ctx context.Context) error {
    // 调用父类的初始化（如果需要）
    if err := a.Agent.Initialize(ctx); err != nil {
        return fmt.Errorf("failed to initialize base agent: %w", err)
    }
    // 绑定配置到自定义字段
    if err := a.BindConfig(&a.YourField); err != nil {
        return fmt.Errorf("failed to bind config: %w", err)
    }
    // 初始化你的第三方客户端
    a.client = thirdparty.NewClient(a.APIKey)
    return nil
}

  2. **Process(ctx context.Context, input adk.Input) ( adk.Output, error)

    • 职责 ：处理单个用户输入（Input）并产生输出（Output）。这是Agent的“大脑”，是业务逻辑的核心所在。
    • 实现要点 ：从 input.Content 获取用户请求。根据请求内容，可能调用内部工具、进行逻辑判断、访问外部API等。最后，构造一个 adk.Output 对象返回。必须妥善处理所有错误，并通过error返回。
    func (a *MyAgent) Process(ctx context.Context, input *adk.Input) (*adk.Output, error) {
    userQuery := input.Content
    // 你的业务逻辑在这里
    result, err := a.client.QuerySomething(ctx, userQuery)
    if err != nil {
        // 使用框架提供的Logger记录错误，比fmt.Println更规范
        a.Logger().Error("Query failed", "error", err, "query", userQuery)
        return nil, fmt.Errorf("处理请求时出错: %w", err)
    }
    // 构造输出
    output := &adk.Output{
        Content: result,
        Metadata: map[string]interface{}{
            "processed_by": "MyAgent",
        },
    }
    return output, nil
}

  3. Shutdown(ctx context.Context) error (可选但推荐)

    • 职责 ：在Agent停止前进行清理工作，如关闭数据库连接、释放资源等。
    • 实现要点 ：即使没有资源需要释放，实现一个空的Shutdown也是一个好习惯，它让生命周期更完整。

3.3 配置管理：让Skill灵活可调

一个健壮的Skill应该将其行为参数化。在 说明.md 中，我会强调使用YAML配置文件。

  1. 定义配置结构 ：在Skill的根目录创建一个 config.yaml 或是在 skill.yaml 中增加配置段落。定义清晰的结构和字段。

    # config.yaml
my_agent:
  api_key: "${API_KEY}" # 支持环境变量注入
  endpoint: "https://api.example.com/v1"
  timeout_seconds: 30
  enable_feature_x: true

  2. 绑定配置到字段 ：如上文 Initialize 方法所示，使用 a.BindConfig(...) 将配置文件的特定部分绑定到Agent结构体的字段上。字段标签 yaml:"field_name" 用于映射。

  3. 环境变量与安全 ：敏感信息如API密钥，绝对不要硬编码。使用 ${VAR_NAME} 语法在YAML中引用环境变量。在Skill的部署说明中，需要明确告知用户需要设置哪些环境变量。

3.4 工具（Tools）集成：扩展Agent能力

如果Agent需要执行特定操作（如调用外部API、查询数据库、运行shell命令），就需要定义和使用Tools。我的Skill需要指导AI如何封装一个操作成为Tool。

  1. 定义Tool结构 ：一个Tool也是一个Go结构体，需要实现 adk.Tool 接口，主要是一个 Execute 方法。

    type WeatherQueryTool struct {
    client *weather.Client
}
func (t *WeatherQueryTool) Execute(ctx context.Context, params map[string]interface{}) (interface{}, error) {
    city, _ := params["city"].(string)
    // 调用天气客户端
    return t.client.GetForecast(ctx, city)
}

  2. 注册Tool到Agent ：在Agent的 Initialize 方法中，将Tool实例注册到框架中，这样在 Process 方法里或通过其他机制就可以调用它。

    func (a *MyAgent) Initialize(ctx context.Context) error {
    // ... 其他初始化
    weatherTool := &WeatherQueryTool{client: a.weatherClient}
    if err := a.RegisterTool("get_weather", weatherTool); err != nil {
        return err
    }
    return nil
}

避坑技巧 ：在指导AI生成Tool相关代码时，要特别强调错误处理和参数类型断言。 params 是 map[string]interface{} ，直接使用前必须进行类型检查，否则极易引发panic。这是新手（包括AI）常踩的坑。

4. 技能创建器（skill-creator）的工作原理推测

虽然我直接使用了 skill-creator 这个黑盒，但根据其行为，我们可以合理推测它的工作流程。这对于理解整个项目的运作和未来自定义类似工具很有帮助。

  1. 解析规格说明 ： skill-creator 首先会读取并解析我提供的 说明.md 文件。它可能使用自然语言处理（NLP）技术来提取关键信息，如技能名称、描述、输入输出格式、核心步骤、代码模板等。更可能的是，它期待 说明.md 遵循某种预定的结构或标记，以便于程序化解析。

  2. 填充代码模板 ： skill-creator 内部应该维护了一套用于生成各种类型Skill的代码模板（Boilerplate）。这些模板是带有占位符的Go文件、YAML文件等。例如，一个 main.go.tmpl 文件。解析完 说明.md 后，它会将提取出的信息（如Agent结构体名、自定义字段、初始化逻辑描述、Process逻辑描述等）填充到这些模板的对应占位符中。

  3. 生成项目结构 ：根据技能类型（这里是Go Agent Skill），它知道需要创建哪些文件和目录。例如：

    • go.mod ：根据模块名和 adk-go 版本生成。
    • main.go ：填充了基于模板和 说明.md 生成的主Agent代码。
    • skill.yaml ：定义了技能的元数据，如名称、版本、作者、入口点等。
    • config.yaml ：根据 说明.md 中提到的配置项，生成一个示例配置文件。
    • README.md ：生成基本的技能使用说明。

  4. 执行上下文感知 ：我给的Prompt中包含了“在当前目录”，所以 skill-creator 会在当前命令行所在的文件系统路径下，创建上述文件和目录，而不是在一个随机位置。

  5. 输出与集成 ：生成所有文件后， skill-creator 的任务就完成了。它可能还会输出一条成功信息。接下来，这个新生成的Skill目录就可以被Cline直接加载和使用，或者由开发者进行进一步的微调和测试。

这个过程本质上是一种 “元编程” 或 “代码生成” 。 skill-creator 是一个高级的代码生成器，而 说明.md 是驱动这个生成器的、对人类和机器都相对友好的“高级配置语言”。这种模式将重复性的、模式化的编码工作自动化，让开发者能更专注于核心逻辑和规则的定义。

5. 从本项目延伸：AI辅助开发的最佳实践

通过完成 skill-write-agent-use-adk-go 这个项目，我总结出一些在AI辅助下进行开发，特别是开发“元工具”的经验。

5.1 清晰定义优于模糊描述

给AI的指令（无论是给Cline的Prompt，还是 说明.md 这样的规格文档）必须极其清晰、无歧义、结构化。避免使用“大概”、“可能”、“类似”这样的词汇。应该使用：

  • 明确的输入输出示例 ：给出一个具体的用户请求例子，以及你期望Skill生成的代码片段例子。
  • 步骤枚举 ：用1、2、3…列出必须完成的步骤。
  • 正反例对比 ：如果某种写法是错误的，直接指出并给出正确写法。例如，“不要使用全局变量，而应该将依赖注入到Agent结构体中”。
  • 术语一致 ：全程使用相同的术语指代同一事物。比如，一直叫它“Agent”而不是有时叫“Bot”有时叫“Handler”。

5.2 分层设计与关注点分离

即使是在一个被AI生成的Skill里，也要保持好的代码结构。在 说明.md 中就要体现这一点：

  • 将配置、逻辑、工具分离 ：指导AI生成独立的配置结构、放在 internal 或 pkg 下的逻辑包、以及专门的 tools 目录。
  • 定义清晰的接口 ：即使AI生成具体实现，也要在说明中强调接口的重要性。例如，“Agent必须实现 adk.Agent 接口”，并列出接口方法。
  • 错误处理统一范式 ：明确规定错误应该如何包装、记录和返回。例如，“所有可能失败的操作都必须返回error，并使用 fmt.Errorf(“context: %w”, err) 格式包装底层错误”。

5.3 测试驱动开发的思维

在编写 说明.md 时，就可以思考这个Skill生成的代码应该如何被测试。可以在文档中加入一个“测试”章节，指导AI生成基本的单元测试骨架。

// 在说明.md中提供测试示例
func TestMyAgent_Process(t *testing.T) {
    agent := NewMyAgent()
    // 如何 mock 配置？如何 mock 外部依赖？
    input := &adk.Input{Content: “test query”}
    output, err := agent.Process(context.Background(), input)
    // 断言 output 和 err
}

这样，生成的Skill就自带了可测试性的基因，鼓励后续开发者补充测试用例。

5.4 文档即代码，代码即文档

这个项目完美体现了“文档即代码”的理念。 说明.md 不仅仅是给人看的开发文档，它本身就是驱动代码生成的“源代码”。同时，最终生成的Skill代码，由于其结构清晰、符合规范，本身也具有很好的可读性，起到了文档的作用。维护好 说明.md ，就相当于维护了Skill的源代码和设计文档。

5.5 迭代与反馈循环

不要期望一次就能写出完美的 说明.md 并生成完美的Skill。我的流程是： 编写 -> 生成 -> 测试 -> 发现问题 -> 修改说明 -> 重新生成/手动修补 。这是一个快速的迭代循环。每次循环都让 说明.md 更精确，让生成的Skill更可靠。把AI生成看作一个“编译”过程，而 说明.md 是你的“高级语言”，你需要不断调试和优化这门“语言”。

6. 常见问题与排查实录

在实际操作和设想他人使用这个Skill时，可能会遇到一些典型问题。这里记录一下我的排查思路。

6.1 问题：生成的代码无法通过 go build 编译

  • 可能原因1：依赖缺失或版本不对 。
    • 排查 ：检查生成的 go.mod 文件，看 adk-go 的版本号是否正确，模块路径是否准确。有时AI可能使用了过时的或错误的导入路径。
    • 解决 ：手动修正 go.mod 中的 require 语句，然后运行 go mod tidy 。
  • 可能原因2： 说明.md 中引用了不存在的类型或函数 。
    • 排查 ：仔细阅读编译错误信息，定位到具体的行和错误（如“undefined: someType”）。然后回到 说明.md 中，检查对应的示例代码或描述，看是否拼写错误，或者假设了某个不存在的包。
    • 解决 ：修正 说明.md 中的错误描述，重新生成，或直接在生成的代码中修正。
  • 可能原因3：未实现所有必要接口方法 。
    • 排查 ：错误信息可能是“*MyAgent does not implement adk.Agent (missing Shutdown method)”。虽然 Shutdown 可能是可选的，但框架最新版本或特定模式可能要求实现。
    • 解决 ：在 说明.md 的模板部分，补全所有接口方法，即使是空实现。然后重新生成。

6.2 问题：Skill能被Cline加载，但处理请求时无响应或报错

  • 可能原因1：Agent的 Initialize 方法失败 。
    • 排查 ：查看Cline或Agent的日志输出。 Initialize 中的错误（如配置绑定失败、网络连接失败）会导致Agent启动即崩溃，无法处理任何请求。
    • 解决 ：确保 说明.md 中关于配置绑定和初始化的逻辑是健壮的，加入了足够的错误处理和日志。在生成的代码中检查 Initialize 方法。
  • 可能原因2： Process 方法逻辑有误或panic 。
    • 排查 ：如果 Initialize 成功，但处理请求时失败，重点检查 Process 方法。是否有未处理的 nil 指针？类型断言是否安全？是否调用了未初始化的客户端？
    • 解决 ：在 说明.md 中强化 Process 方法的错误处理范例。强调对所有外部调用和类型转换进行防御性编程。可以在生成的代码中加入更多的 if err != nil 检查和 log 语句。
  • 可能原因3：输入输出格式不匹配 。
    • 排查 ：Cline调用Skill时传递的 adk.Input 结构，与Skill中 Process 方法期望的格式是否一致？Skill返回的 adk.Output 格式是否符合Cline的预期？
    • 解决 ：在 说明.md 中明确定义输入输出的数据结构。最好提供一个完整的、端到端的示例，从用户输入到Agent内部处理再到最终输出。

6.3 问题：生成的代码风格混乱或不符合团队规范

  • 可能原因： 说明.md 中未定义代码风格 。
    • 解决 ：在 说明.md 的开头或专门章节，明确代码风格要求。例如：

      “所有生成的Go代码必须使用 gofmt 格式化。” “错误信息字符串应使用小写字母开头，不以标点结尾。” “导包分组：标准库、第三方库、内部库，用空行分隔。” “结构体字段标签使用反引号，yaml键名使用snake_case。” 这样， skill-creator 在填充模板时，可能会应用一些基本的格式化规则，或者至少生成的代码有一个一致的基线。

6.4 问题：如何为生成的Skill添加更复杂的功能？

  • 解答 ： skill-creator 根据 说明.md 生成的是一个“最小可行产品”（MVP）级别的Skill。对于复杂功能（如集成数据库、消息队列、复杂的中间件链），通常有两种路径：
    1. 增强 说明.md ：将复杂功能的实现模式也抽象成模板，写入 说明.md 。但这要求 说明.md 的解析器（或 skill-creator ）能理解这些复杂结构，难度较高。
    2. 生成后手动迭代 ：这是更实际的做法。利用AI生成一个正确、可运行的基础骨架，然后由开发者在此基础上，像开发普通Go项目一样，手动添加数据库驱动、消息队列客户端、自定义中间件等复杂功能。AI帮你解决了“从0到1”和框架集成的问题，“从1到10”的深化工作则由你完成。

这个过程让我深刻体会到，在AI时代，开发者的核心价值正在从“编写每一行代码”向“定义问题、设计规则、组装系统、确保质量”转移。 skill-write-agent-use-adk-go 这个项目本身，就是这种新范式的一次具体实践。它不再是一个简单的工具，而是一个用于生产工具的“工厂”。当你需要批量创建某一类标准化产品时，投资搭建这样一个“工厂”，长远来看会带来巨大的效率红利。

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

Agent执行Shell命令：Docker沙箱真的能防住恶意rm -rf吗？

avatar 龙虾开发者社区
cover

Slack 消息通道实战：Socket Mode 穿透内网 vs 公网 Webhook 的 Agent 安全选型

avatar 龙虾开发者社区
cover

OpenClaw 密钥路由实战：多厂商 API 熔断与动态配额管理

avatar 龙虾开发者社区