Skill

Package a capability once, reuse it across agents.

What it is

Skills are reusable agent capabilities defined as local SKILL.md files. A skill can describe how to perform a task (including when and how to call tools), and can be exposed to an agent as a callable tool.

The examples/skills example demonstrates the full flow: discover local skills, turn them into tools, and let an agent use them.

Skill layout

A skill lives in its own directory and includes a SKILL.md. Skills can also ship helper scripts under scripts/. 

examples/skills/
  skills/
    get-random-quote/
      SKILL.md
      scripts/
        get_random_quote/
          main.go

SKILL.md format

Skills are written in Markdown with a small YAML frontmatter header. The body describes when to use the skill and the execution contract. 

---
name: get-random-quote
description: Fetches and returns a single random quote by running the Go script scripts/get_random_quote/main.go.
---

# Random Quote Retriever

## Overview

Use this skill when the user asks for a random quote (inspirational, motivational, general). This skill must retrieve the quote by executing the repository's Go script and returning its stdout.

## How It Works

### Primary Action

- Always run `go run ./scripts/get_random_quote/main.go` via the `bash` tool.
- Return exactly the quote line printed by the program (trim surrounding whitespace).

Tip: keep the contract concrete (exact command, expected stdout, and error behavior). This makes it easier for an agent to use the skill reliably.

Default tools available to skills

Each skill is executed by an internal agent. The agent automatically gets a small built-in toolbox rooted at the skill directory: view, create_file, str_replace, and bash.

That means a skill can inspect local files, edit them, or run commands without extra setup in your application code.

Example: a skill-backed script

The bundled get-random-quote skill fetches a quote by running a small Go program through the skill's bash tool. 

# From examples/skills/skills/get-random-quote/SKILL.md

1. Run the script:
   go run ./scripts/get_random_quote/main.go
2. Return the stdout output exactly as printed, trimming surrounding whitespace.
3. If the script fails, surface the error instead of fabricating a quote.
// From examples/skills/skills/get-random-quote/scripts/get_random_quote/main.go

httpReq, err := http.NewRequestWithContext(
    context.Background(),
    "GET",
    "https://zenquotes.io/api/random",
    http.NoBody,
)
// ...
fmt.Printf("%s - %s\n", data[0].Q, data[0].A)

Example: discover skills and add them to an agent

In the example, skills are loaded from a local directory (./skills), parsed, converted into tools, and then registered on an agent. 

// From examples/skills (edited for brevity)

skillParser := skill.New("./skills")
list, err := skillParser.List()
if err != nil {
    panic(err)
}

tools := make([]*llm.Tool, 0, len(list))
for _, skillName := range list {
    s, err := skillParser.Parse(skillName)
    if err != nil {
        panic(err)
    }

    tool, err := s.AsTool(
        llmClient,
        // Optional: give the skill-agent memory so it can do multi-step work.
        skill.WithMemory(memory.New(20)),
        // Optional: prevent runaway tool loops.
        skill.WithMaxIterations(10),
    )
    if err != nil {
        panic(err)
    }
    tools = append(tools, tool)
}

// register each skill tool on the agent
for _, tool := range tools {
    _ = a.AddTool(tool)
}

The examples/skills program uses memory/jsonfile for persistent history, and also adds a separate file-writing tool with interactive approval middleware.

Run the example

The example loads skills from a relative path (./skills) and stores history in memory.json, so run it from its directory. Provider setup depends on your chosen LLM; follow the example README. 

cd ./examples/skills

go run .

You’ll be prompted to approve tool actions (like running commands or writing files). Reply y to allow.

When to use skills

Related packages