agents-go

Skills

The github.com/zzir/agents-go/skills module implements the open Agent Skills format: a skill is a directory with a SKILL.md (YAML frontmatter + Markdown instructions), optionally bundling scripts/, references/ and assets/. It is a separate module so the YAML dependency stays out of the core SDK.

Skills map onto plain SDK primitives — no sandbox required — following the format’s progressive disclosure:

Stage	Agent Skills	This module
Discovery	load name + description	RenderIndex → agent instructions
Activation	read SKILL.md	ReadFileTool (model reads on demand)
Execution	run scripts / read refs	ReadFileTool; scripts via sandbox.CodeTool (optional)

Usage

import "github.com/zzir/agents-go/skills"

loaded, _ := skills.Load("./skills") // scan dirs, parse each SKILL.md frontmatter

agent := &agents.Agent{
    Name: "assistant",
    Instructions: agents.InstructionsFunc(func(ctx context.Context, rc *agents.RunContext, a *agents.Agent) (string, error) {
        return base + "\n" + skills.RenderIndex(loaded), nil // discovery
    }),
    Tools: []agents.Tool{skills.ReadFileTool("./skills")},   // activation / execution
}

• Load(dir) scans immediate subdirectories for a SKILL.md, validates the frontmatter (name 1–64 lowercase letters/digits/hyphens matching the directory name; description ≤1024 chars; optional license/compatibility/metadata/allowed-tools), and returns skills sorted by name. A directory without a SKILL.md is skipped; a present-but-invalid one is an error.
• RenderIndex(skills) builds the discovery section (each skill’s name, description and path, plus how-to-use guidance) to add to an agent’s instructions. The skill body is not loaded here — progressive disclosure keeps the context footprint small.
• ReadFileTool(dir) is a read_skill_file function tool that lets the model read a file under dir on demand (a SKILL.md body, reference, asset, or script). Reads are confined to dir via Go’s os.Root, so ../ traversal and symlink escapes are rejected, and each read is capped at 256 KiB.

Difference from the Python SDK

Python ships skills as a sandbox capability (agents.sandbox.capabilities.skills), tied to its workspace/manifest sandbox model. This module instead implements the provider-agnostic Agent Skills standard directly on Instructions + a function tool, with no sandbox dependency.

A runnable example is in skills/example.

This site is open source. Improve this page.