skillkit

Documentation

Overview

Package skillkit owns the skill catalog: it embeds skill content into the af binary, installs / uninstalls / lists skills against multiple coding-agent targets (Claude Code, Codex, Gemini, OpenCode, Aider, Windsurf, Cursor), and tracks state in ~/.agentfield/skills/.state.json.

The canonical on-disk layout (after `af skill install`) is:

~/.agentfield/skills/
├── .state.json                                # tracking
└── <skill-name>/
    ├── current → ./<active-version>/         # symlink
    └── <version>/                            # versioned store
        ├── SKILL.md
        └── references/
            └── ...

Each target then either:

• symlinks into ~/.<agent>/skills/<name> (Claude Code style), OR
• appends a marker block to the agent's global rules file pointing at the canonical SKILL.md path so updates flow through automatically.

New skills are added by dropping a directory into skill_data/ and registering it in catalog.go. The skill content is embedded at build time via go:embed (the source-of-truth lives in repo-root skills/<name>/ — keep them in sync via scripts/sync-embedded-skills.sh).

Index

• Variables
• func CanonicalRoot() (string, error)
• func RegisterTarget(t Target)
• func SaveState(s *State) error
• func Uninstall(opts UninstallOptions) error
• type InstallOptions
• type InstallReport
  • func Install(opts InstallOptions) (*InstallReport, error)
  • func Update(skillName string) (*InstallReport, error)
• type InstalledSkill
  • func (i InstalledSkill) SortedTargetNames() []string
• type InstalledTarget
• type Skill
  • func CatalogByName(name string) (Skill, error)
  • func (s Skill) EntryContent() ([]byte, error)
  • func (s Skill) EnumerateFiles() (map[string][]byte, error)
• type SkipReason
• type State
  • func ListInstalled() (*State, error)
  • func LoadState() (*State, error)
• type Target
  • func AllTargets() []Target
  • func DetectedTargets() []Target
  • func TargetByName(name string) (Target, error)
• type TargetError
• type UninstallOptions

Variables

var Catalog = []Skill{
	{
		Name:        "agentfield-multi-reasoner-builder",
		Version:     "0.3.0",
		Description: "Architect and ship complete multi-agent backends on AgentField — composite intelligence from five foundational principles, deep dynamic call graphs, async-first smoke tests, and hard runtime-contract rules.",
		EmbedRoot:   "skill_data/agentfield-multi-reasoner-builder",
		EntryFile:   "SKILL.md",
	},
}

Catalog is the registry of every skill the binary ships. Add a new entry here when adding a new skill, and drop the source files into skill_data/<name>/ so the embed picks them up.

var SkillData embed.FS

SkillData is the embedded filesystem containing the source-of-truth content for every shipped skill. Files live under skill_data/<skill-name>/ and are copied from the repo-root skills/ directory at build time.

Functions

func CanonicalRoot

func CanonicalRoot() (string, error)

CanonicalRoot returns ~/.agentfield/skills/. Honors $AGENTFIELD_HOME if set (useful for tests and for users who want a non-default location).

func RegisterTarget

func RegisterTarget(t Target)

RegisterTarget adds a target to the global registry. Called from init() in each per-target file.

func SaveState

func SaveState(s *State) error

SaveState writes the state file atomically (write-temp + rename).

func Uninstall

func Uninstall(opts UninstallOptions) error

Types

type InstallOptions

type InstallOptions struct {
	SkillName     string   // canonical skill name; empty = first in catalog
	Version       string   // explicit version; empty = current binary's embedded version
	Targets       []string // explicit target list; empty = use AllDetected/AllRegistered/Selection
	AllDetected   bool     // install into every target Detected() reports true
	AllRegistered bool     // install into every registered target (even undetected)
	Force         bool     // re-install even if state shows the same version is already present
	DryRun        bool     // print what would happen, don't write
}

InstallOptions controls how a skill is installed across targets.

type InstallReport

type InstallReport struct {
	Skill            Skill
	CanonicalDir     string // ~/.agentfield/skills/<name>/<version>
	CurrentLink      string // ~/.agentfield/skills/<name>/current
	WroteCanonical   bool
	TargetsInstalled []InstalledTarget
	TargetsSkipped   []SkipReason
	TargetsFailed    []TargetError
}

InstallReport summarizes one install operation. The CLI uses this to print a clean handoff message.

func Install

func Install(opts InstallOptions) (*InstallReport, error)

Install runs an install pass according to opts. It performs the canonical write first, switches the `current` symlink, then installs into each selected target. Idempotent and safe to re-run.

func Update

func Update(skillName string) (*InstallReport, error)

Update is a convenience wrapper that re-installs the skill into every target it's currently installed at, using the binary's embedded version.

type InstalledSkill

type InstalledSkill struct {
	CurrentVersion    string                     `json:"current_version"`
	InstalledAt       time.Time                  `json:"installed_at"`
	AvailableVersions []string                   `json:"available_versions"`
	Targets           map[string]InstalledTarget `json:"targets"`
}

InstalledSkill records the installed-version state of a single skill.

func (InstalledSkill) SortedTargetNames

func (i InstalledSkill) SortedTargetNames() []string

SortedTargetNames returns the keys of the Targets map in stable order so `af skill list` output is deterministic.

type InstalledTarget

type InstalledTarget struct {
	TargetName  string    `json:"target_name"` // "claude-code", "codex", ...
	Method      string    `json:"method"`      // "symlink", "marker-block", "manual"
	Path        string    `json:"path"`        // file or directory the integration writes to
	Version     string    `json:"version"`     // version installed at this target
	InstalledAt time.Time `json:"installed_at"`
}

InstalledTarget records one target integration for one skill.

type Skill

type Skill struct {
	Name        string // canonical skill name (kebab-case, used as directory name)
	Version     string // semver-ish version string baked into the binary
	Description string // one-line description for `af skill list`
	EmbedRoot   string // root path inside SkillData where this skill's files live
	EntryFile   string // relative path to the skill's main file (usually SKILL.md)
}

Skill describes a skill that ships with the af binary. The catalog below is the only place new skills get registered. Bump Version on every change so `af skill update` knows there's a new build.

func CatalogByName

func CatalogByName(name string) (Skill, error)

CatalogByName returns the skill with the given name, or an error if it is not in the registry.

func (Skill) EntryContent

func (s Skill) EntryContent() ([]byte, error)

EntryContent returns the raw bytes of the skill's entry file (SKILL.md). Used by `af skill install --print` and by Cursor's clipboard fallback.

func (Skill) EnumerateFiles

func (s Skill) EnumerateFiles() (map[string][]byte, error)

EnumerateFiles walks the embedded skill data and returns every file path relative to the skill's EmbedRoot, paired with its raw bytes. Used by the installer to write the canonical on-disk copy.

type SkipReason

type SkipReason struct {
	TargetName string
	Reason     string
}

type State

type State struct {
	Version string                    `json:"state_version"`
	Skills  map[string]InstalledSkill `json:"skills"`
}

State is the on-disk record of which skills are installed, at which version, and which target integrations are active. Persisted at ~/.agentfield/skills/.state.json.

func ListInstalled

func ListInstalled() (*State, error)

ListInstalled returns the on-disk state for `af skill list`.

func LoadState

func LoadState() (*State, error)

LoadState reads the state file from disk. If the file does not exist yet, returns an empty State so first-install flows just write fresh.

type Target

type Target interface {
	Name() string                                                             // canonical short name, e.g. "claude-code"
	DisplayName() string                                                      // pretty name for UI, e.g. "Claude Code"
	Detected() bool                                                           // is this target installed on the user's machine?
	Method() string                                                           // "symlink", "marker-block", "manual"
	TargetPath() (string, error)                                              // canonical path the target writes to
	Install(skill Skill, canonicalCurrentDir string) (InstalledTarget, error) // performs the install (idempotent)
	Uninstall() error                                                         // removes the integration
	Status() (installed bool, version string, err error)                      // currently installed?
}

Target is a coding-agent integration the skill can be installed into. Each target knows how to detect itself, install, uninstall, and report its current installed version (if any).

func AllTargets

func AllTargets() []Target

AllTargets returns the registered targets.

func DetectedTargets

func DetectedTargets() []Target

DetectedTargets returns the subset of registered targets that are currently installed on the user's machine.

func TargetByName

func TargetByName(name string) (Target, error)

TargetByName looks up a target by its short name.

type TargetError

type TargetError struct {
	TargetName string
	Err        error
}

type UninstallOptions

type UninstallOptions struct {
	SkillName       string
	Targets         []string
	RemoveCanonical bool
}

Uninstall removes a skill from the named targets (or all if empty), and optionally drops the canonical store entirely (if RemoveCanonical=true).