skills

Documentation

Overview

Package skills gives memcode discoverable, lazy-loaded "traits" — the same mechanism Claude Code uses: a markdown file with a name + a "when to use" blurb, its body loaded on demand when the model decides a task matches. The system prompt only POINTS at the skill dirs (see Roots) — the model greps/reads them when a task fits, rather than every skill's blurb being dumped into context.

Discovery is UNIVERSAL (see discoveryRoots): it doesn't matter whether a skill was installed user-global, at the repo root, or in a monorepo subfolder, nor whether its dir is a real one or a symlink an installer dropped. memcode unifies its own skills with the cross-agent Agent Skills standard (.agents/skills, what the `skills` CLI installs) and Claude Code's dirs — so claude-api, vercel:*, supabase, etc. all come along for free.

The trust boundary is "installed": a skill only exists because someone put a file in one of these roots (or installed a plugin), so loading its body is safe.

Index

• func RemoteAdd(ctx context.Context, dir, pkg string) (string, error)
• func Roots(repoRoot string) []string
• func RootsIn(repoRoot string, extraRoots []string) []string
• type RemoteSkill
  • func RemoteFind(ctx context.Context, query, owner string) ([]RemoteSkill, error)
• type Skill
  • func Discover(repoRoot string) []Skill
  • func DiscoverIn(repoRoot string, extraRoots []string) []Skill
  • func Search(sk []Skill, query string, max int) []Skill
  • func (s Skill) Load() (string, error)
  • func (s Skill) Validate() []string

Functions

func RemoteAdd

func RemoteAdd(ctx context.Context, dir, pkg string) (string, error)

RemoteAdd installs a skill package ("owner/repo" or "owner/repo@skill") into dir's .agents/skills via the `skills` CLI. This EXECUTES external code and writes files — callers MUST gate it. Returns the (ANSI-stripped) CLI output on success.

func Roots

func Roots(repoRoot string) []string

Roots returns the EXISTING skill source directories, in precedence order — the universal set (see discoveryRoots): memcode's own, the Agent Skills .agents/skills convention (user-global + anywhere in the repo), and Claude Code's dirs. Pointed at from the system prompt so the model can grep/read them on demand instead of having every skill's blurb dumped into context.

func RootsIn

func RootsIn(repoRoot string, extraRoots []string) []string

RootsIn is Roots plus caller-supplied extra roots (see DiscoverIn).

Types

type RemoteSkill

type RemoteSkill struct {
	Package  string // "owner/repo@skill" — the argument to `skills add`
	Installs string // reported install count, e.g. "509.5K" (informational)
	URL      string // https://skills.sh/owner/repo/skill
}

RemoteSkill is one search hit from the skills.sh catalog.

func RemoteFind

func RemoteFind(ctx context.Context, query, owner string) ([]RemoteSkill, error)

RemoteFind searches the skills.sh catalog for a query (optionally scoped to a GitHub owner). Read-only; needs network + node/npx. Returns the parsed matches.

type Skill

type Skill struct {
	Name          string            // unique slug — plugin skills are namespaced (e.g. "vercel:ai-sdk")
	Description   string            // the "when to use" blurb shown in the catalog
	License       string            // SPDX id, optional (spec)
	Compatibility string            // declared agent/runtime compatibility, optional (spec)
	AllowedTools  string            // experimental tool scope, e.g. "Bash(git:*) Read" (spec)
	Version       string            // metadata.version, optional (spec parks version under metadata)
	Metadata      map[string]string // the full metadata map (author, version, argument-hint, …)
	Path          string            // the SKILL.md / *.md file holding the body
	Dir           string            // the skill's directory (bundled scripts/files the body may reference)
}

Skill is one discovered trait: its frontmatter (the Agent Skills open spec, agentskills.io) plus where its body lives. Required spec fields: Name, Description. Optional spec fields: License, Compatibility, AllowedTools (experimental), and a free-form Metadata map (where the spec parks Version, author, argument-hint, …).

func Discover

func Discover(repoRoot string) []Skill

Discover scans the universal roots and returns one skill per name, with repo-local skills overriding user-global ones and, within a source, the newest file winning.

func DiscoverIn

func DiscoverIn(repoRoot string, extraRoots []string) []Skill

DiscoverIn is Discover plus caller-supplied extra roots (e.g. a gateway agent's own skills dir), which rank between repo-local and user-global.

func Search

func Search(sk []Skill, query string, max int) []Skill

Search ranks installed skills against a query — a technology / library / CLI / topic the agent is about to work with (e.g. "supabase", "next.js", "stripe") — and returns the best matches (at most max). Unlike the old always-on catalog, this runs ONLY when the model explicitly asks (the `skill` find tool), so there's no per-turn context cost and no brittle auto-gating: the agent supplies the query when it recognizes a 3rd-party tool. A whole-query substring hit scores strongest; individual query tokens add to it.

func (Skill) Load

func (s Skill) Load() (string, error)

Load returns the skill's body — everything after the frontmatter block.

func (Skill) Validate

func (s Skill) Validate() []string

Validate reports a skill's deviations from the Agent Skills spec (agentskills.io) — empty means conformant. memcode discovers LENIENTLY (a non-conformant skill still loads), so this surfaces conformance for auditing/warnings; it does not gate discovery.