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 tool-call 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 the Go program at `scripts/get_random_quote/main.go` via the `go` 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.

Example: a skill-backed script

The bundled get-random-quote skill fetches a quote by running a small Go program. 

// 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)
    if err != nil {
        panic(err)
    }
    tools = append(tools, tool)
}

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

The example also adds a file-writing tool with interactive validation so the user can approve writes.

Run the example

The example loads skills from a relative path (./skills), 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