skill-ref-go

Go port of the Agent Skills reference tooling. It mirrors the Python skills-ref CLI by parsing SKILL.md frontmatter, validating metadata, and generating <available_skills> prompt snippets while also exposing a consumable Go package.

Requirements

• Go 1.24+ (tested with Go 1.25.4 toolchain)

Installation

# Install the CLI
go install github.com/rokku-c/skill-ref-go/cmd/skills-ref@latest

The binary skills-ref lands in your $GOBIN (default $GOPATH/bin).

CLI usage

# Validate a skill directory (or SKILL.md file)
skills-ref validate path/to/skill

# Read skill properties as JSON
echo "$(skills-ref read-properties path/to/skill)"

# Generate <available_skills> XML for prompts
skills-ref to-prompt path/to/skill-a path/to/skill-b

• Passing a SKILL.md file is also supported; it is resolved to the parent directory automatically.
• Validation failures exit with status 1 and list each error.

Go library usage

package main

import (
    "fmt"

    "github.com/rokku-c/skill-ref-go/pkg/skillsref"
)

func main() {
    if problems := skillsref.Validate("./my-skill"); len(problems) > 0 {
        for _, err := range problems {
            fmt.Println("validation error:", err)
        }
        return
    }

    props, err := skillsref.ReadProperties("./my-skill")
    if err != nil {
        panic(err)
    }
    fmt.Printf("%s — %s\n", props.Name, props.Description)

    prompt, err := skillsref.ToPrompt([]string{"./my-skill"})
    if err != nil {
        panic(err)
    }
    fmt.Println(prompt)
}

The package focuses on parsing and validating frontmatter; it intentionally avoids executing any skill logic.

Development

# Format
 gofmt -w ./cmd ./pkg
# Test (adjust GOROOT if your environment overrides it)
 GOROOT=/usr/local/go go test ./...