skillsmith

README

skillsmith

Ship embedded Agent Skills with your Go CLI.

What is skillsmith?

skillsmith is a Go library for distributing Agent Skills through your CLI tool. Agent Skills are an open format for giving AI agents new capabilities — portable instruction sets that work across Claude Code, GitHub Copilot, OpenAI Codex, and other compatible agents.

With skillsmith, you can embed skill files into your Go binary using embed.FS and expose a skills subcommand that lets users install, update, and manage those skills on their machine. This makes your CLI tool AI-agent-friendly without pulling in a full CLI framework.

Synopsis

//go:embed skills
var skillsFS embed.FS

func run(ctx context.Context, args []string) error {
    if len(args) > 0 && args[0] == "skills" {
        s, err := skillsmith.New("mytool", version, skillsFS)
        if err != nil {
            log.Fatal(err)
        }
        return s.Run(ctx, args[1:])
    }
    // ... existing command handling
    return nil
}

This gives your tool the following subcommands:

mytool skills list        # List embedded skills
mytool skills install     # Install skills to ~/.agents/skills
mytool skills update      # Update skills to newer versions
mytool skills reinstall   # Reinstall all managed skills
mytool skills uninstall   # Remove managed skills
mytool skills status      # Show install status and version diff

Features

• Drop-in integration — add a skills subcommand to your existing CLI with a few lines of code
• No CLI framework dependency — uses the standard flag package only
• embed.FS support — embed skill files in your binary; the skills/ prefix is auto-detected and stripped
• agentskills compliant — follows the open Agent Skills specification for SKILL.md format and directory structure
• Metadata tracking — writes .skillsmith.json alongside each installed skill for version-aware update and uninstall
• Semantic versioning — uses semver.Compare for version comparison; prevents accidental downgrades
• Lenient validation — warns on name mismatches; only skips skills with missing descriptions or unparseable YAML
• agentskills subpackage — SKILL.md parsing and discovery can be used independently of the CLI layer

Options

Option	Description
--prefix	Override the install directory (ignores --scope)
--scope	user (default: ~/.agents/skills) or repo (auto-detects repository root)
--dry-run	Preview changes without applying
--force	Overwrite unmanaged skills or force downgrade

Installation

% go get github.com/Songmu/skillsmith

Author

Songmu

Documentation

Index

• func DemoFS() fs.FS
• func InstallDirForScope(scope string) (string, error)
• func IsManaged(dir string) bool
• func Run(ctx context.Context, argv []string, outStream, errStream io.Writer) error
• func Version() string
• func WriteMeta(dir string, meta *SkillMeta) error
• type CopyMode
• type CopyOptions
• type CopyResult
  • func CopySkills(src fs.FS, destDir string, opts CopyOptions) (*CopyResult, error)
  • func (r *CopyResult) Installed() []SkillAction
  • func (r *CopyResult) Skipped() []SkillAction
  • func (r *CopyResult) Warned() []SkillAction
• type Options
• type SkillAction
• type SkillMeta
  • func ReadMeta(dir string) (*SkillMeta, error)
• type SkillStatus
• type Smith
  • func New(name, version string, skillFS fs.FS) (*Smith, error)
  • func (s *Smith) Install(ctx context.Context, opts Options) (*CopyResult, error)
  • func (s *Smith) List(ctx context.Context) ([]*agentskills.Skill, error)
  • func (s *Smith) Name() string
  • func (s *Smith) Reinstall(ctx context.Context, opts Options) (*CopyResult, error)
  • func (s *Smith) Run(ctx context.Context, args []string) error
  • func (s *Smith) Status(ctx context.Context, opts Options) (*StatusResult, error)
  • func (s *Smith) Uninstall(ctx context.Context, opts Options) (*UninstallResult, error)
  • func (s *Smith) Update(ctx context.Context, opts Options) (*CopyResult, error)
  • func (s *Smith) Version() string
• type StatusResult
• type UninstallAction
• type UninstallResult

Functions

func DemoFS

func DemoFS() fs.FS

DemoFS returns the embedded demo skills filesystem. The "skills/" prefix is stripped automatically by Smith.skillsFS().

func InstallDirForScope

func InstallDirForScope(scope string) (string, error)

InstallDirForScope returns the skill installation directory for the given scope. An empty scope defaults to "user".

• user (default): ~/.agents/skills (absolute, under the user's home directory)
• repo: <repo-root>/.agents/skills (absolute, under the repository root found by traversing parent directories for .git)

func IsManaged

func IsManaged(dir string) bool

IsManaged reports whether a .skillsmith.json file exists in dir.

func Run

func Run(ctx context.Context, argv []string, outStream, errStream io.Writer) error

Run the skillsmith

func Version

func Version() string

Version returns the current version string.

func WriteMeta

func WriteMeta(dir string, meta *SkillMeta) error

WriteMeta writes meta as .skillsmith.json into dir.

Types

type CopyMode

type CopyMode int

CopyMode controls the install/update/reinstall behavior.

const (
	// ModeInstall installs new skills; skips existing managed skills.
	ModeInstall CopyMode = iota
	// ModeUpdate re-installs managed skills whose version has changed.
	ModeUpdate
	// ModeReinstall overwrites all managed skills regardless of version.
	ModeReinstall
)

type CopyOptions

type CopyOptions struct {
	// Mode determines whether this is an install, update, or reinstall.
	Mode CopyMode
	// Force allows overwriting unmanaged (externally placed) skills.
	Force bool
	// DryRun reports what would happen without making any changes.
	DryRun bool
	// Name is the tool name written to .skillsmith.json (installedBy).
	Name string
	// Version is the tool version written to .skillsmith.json.
	Version string
}

CopyOptions configures the behavior of CopySkills.

type CopyResult

type CopyResult struct {
	Actions []SkillAction
}

CopyResult summarizes the outcome of a CopySkills call.

func CopySkills

func CopySkills(src fs.FS, destDir string, opts CopyOptions) (*CopyResult, error)

CopySkills copies skills from src (an fs.FS whose top-level directories are skill directories) into destDir.

func (*CopyResult) Installed

func (r *CopyResult) Installed() []SkillAction

Installed returns the actions whose Action is "installed", "updated", or "reinstalled".

func (*CopyResult) Skipped

func (r *CopyResult) Skipped() []SkillAction

Skipped returns the actions whose Action is "skipped".

func (*CopyResult) Warned

func (r *CopyResult) Warned() []SkillAction

Warned returns the actions whose Action is "warned".

type Options

type Options struct {
	DryRun bool
	Prefix string
	Scope  string
	Force  bool
}

Options holds parameters shared by most subcommands. CLI frameworks can populate this struct directly and pass it to the exported operation methods (Install, Update, etc.) without going through Run / flag parsing.

type SkillAction

type SkillAction struct {
	Dir     string
	Action  string // "installed", "updated", "reinstalled", "skipped", "warned"
	Message string
}

SkillAction describes what happened to a single skill during CopySkills.

type SkillMeta

type SkillMeta struct {
	InstalledBy string    `json:"installedBy"`
	Version     string    `json:"version"`
	InstalledAt time.Time `json:"installedAt"`
}

SkillMeta holds metadata written alongside an installed skill.

func ReadMeta

func ReadMeta(dir string) (*SkillMeta, error)

ReadMeta reads .skillsmith.json from the given skill directory. It returns an error when the file cannot be read or decoded.

type SkillStatus

type SkillStatus struct {
	Dir              string
	Installed        bool
	InstalledVersion string
	AvailableVersion string
	UpToDate         bool
	MetadataError    error
}

SkillStatus describes the installation status of a single skill.

type Smith

type Smith struct {
	// FlagSet is the top-level flag set, created by New.
	FlagSet *flag.FlagSet
	// OutWriter is the writer for normal output (defaults to os.Stdout).
	OutWriter io.Writer
	// ErrWriter is the writer for error / diagnostic output (defaults to os.Stderr).
	ErrWriter io.Writer
	// contains filtered or unexported fields
}

Smith is the main entry point for the skillsmith skills subcommand. Create one with New and call Run to dispatch to the appropriate subcommand.

func New

func New(name, version string, skillFS fs.FS) (*Smith, error)

New creates a Smith with the given name, version and skill filesystem.

Version validation: if version does not start with "v", one is prepended for validation only. The version is stored as provided.

FS auto-detection: if the root of skillFS contains exactly one directory named "skills" (files at root are ignored), that directory is used as the skill root via fs.Sub. Otherwise skillFS is used as-is.

func (*Smith) Install

func (s *Smith) Install(ctx context.Context, opts Options) (*CopyResult, error)

Install installs skills that are not yet present.

func (*Smith) List

func (s *Smith) List(ctx context.Context) ([]*agentskills.Skill, error)

List returns the discovered skills from the embedded filesystem.

func (*Smith) Name

func (s *Smith) Name() string

Name returns the name of the hosting CLI tool.

func (*Smith) Reinstall

func (s *Smith) Reinstall(ctx context.Context, opts Options) (*CopyResult, error)

Reinstall reinstalls all managed skills regardless of version.

func (*Smith) Run

func (s *Smith) Run(ctx context.Context, args []string) error

Run parses args and dispatches to the matching subcommand.

func (*Smith) Status

func (s *Smith) Status(ctx context.Context, opts Options) (*StatusResult, error)

Status checks the installation status of skills.

func (*Smith) Uninstall

func (s *Smith) Uninstall(ctx context.Context, opts Options) (*UninstallResult, error)

Uninstall removes managed skills.

func (*Smith) Update

func (s *Smith) Update(ctx context.Context, opts Options) (*CopyResult, error)

Update updates managed skills whose version has changed.

func (*Smith) Version

func (s *Smith) Version() string

Version returns the version string as provided to New.

type StatusResult

type StatusResult struct {
	Skills []SkillStatus
}

StatusResult summarizes the outcome of a Status call.

type UninstallAction

type UninstallAction struct {
	Dir     string
	Action  string // "uninstalled", "skipped"
	Message string
}

UninstallAction describes what happened to a single skill during Uninstall.

type UninstallResult

type UninstallResult struct {
	Actions []UninstallAction
}

UninstallResult summarizes the outcome of an Uninstall call.