agentskill

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 25, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package agentskill bundles the canonical "promptvm" Agent Skill with the CLI and installs it into the local agent skills directories for Claude Code and Codex, so any agent session already knows how to drive PromptVM.

Both agents read the same folder-shaped Agent Skill format (<skills-dir>/<name>/SKILL.md with YAML frontmatter):

  • Claude Code: ~/.claude/skills (user) or ./.claude/skills (project)
  • Codex: $CODEX_HOME/skills else ~/.agents/skills (user), or ./.agents/skills (project)

Index

Constants

View Source 
const (
	// Name is the skill folder + frontmatter name (valid kebab per
	// internal/skills.ValidateName).
	Name = "promptvm"

	// Version is the bundled skill revision. Bump it whenever the embedded
	// data/promptvm content changes so `agent status` and first-run can detect
	// that an update is available.
	Version = 1
)
View Source 
const (
	// StatusInstalled means the skill was written to disk.
	StatusInstalled = "installed"
	// StatusSkipped means the user opted out (reserved; the env opt-out
	// currently short-circuits before writing a marker).
	StatusSkipped = "skipped"
	// StatusNotInstalled is reported by `agent status` when no marker exists.
	// It is never persisted.
	StatusNotInstalled = "not-installed"
)

Status values for the tracker marker.

Variables

This section is empty.

Functions

func Checksum 

func Checksum() string

Checksum returns the sha256 of the bundled SKILL.md, for change detection.

func Clear 

func Clear() error

Clear removes the marker file. A missing file is not an error.

func Exists 

func Exists() (bool, error)

Exists reports whether the marker file is present (any status).

func Files 

func Files() ([]string, error)

Files returns the bundled file paths relative to the skill folder root, with forward slashes, sorted.

func TrackerPath 

func TrackerPath() (string, error)

TrackerPath returns the marker path (config.Dir()/agent-skill.json).

func Uninstall 

func Uninstall(paths []string) error

Uninstall removes the given promptvm skill folders. The paths come from the tracker (an on-disk, user-editable file), so it defends against a corrupted or hand-edited marker: it cleans each path, removes only folders whose final element is the skill name, and refuses to follow a symlinked leaf. A missing folder is not an error.

Types

type InstalledTarget 

type InstalledTarget struct {
	Key  string `json:"key"`
	Path string `json:"path"`
}

InstalledTarget records where the skill was written.

func Install 

func Install(scope Scope, targets []Target, force bool) ([]InstalledTarget, error)

Install writes the bundled skill into each target's skill folder for the given scope and returns the per-target install locations.

When a target's promptvm folder already exists and force is false, Install behaves as follows based on the installed SKILL.md:

  • checksum matches the bundle → idempotent no-op
  • folder has no readable SKILL.md → treated as not installed; repaired
  • checksum differs → error (use force to overwrite)

On error the returned slice contains the targets installed before the failure (Install processes targets sequentially and stops at the first one that errors).

func InstallBestEffort 

func InstallBestEffort(scope Scope, targets []Target) []InstalledTarget

InstallBestEffort installs each target independently, skipping (rather than aborting on) any target that errors, and returns the targets that did install. Used by first-run auto-install so a pre-existing/conflicting folder for one agent never blocks installing the other — or permanently wedges the first-run path before a marker can be written.

type Scope 

type Scope string

Scope selects user-global vs project-local installation. 

const (
	// ScopeUser installs into the user's home agent directories.
	ScopeUser Scope = "user"
	// ScopeProject installs into the current working directory.
	ScopeProject Scope = "project"
)

type Target 

type Target struct {
	Key   string // "claude" | "codex"
	Label string // human-readable label
}

Target is one agent's skills location.

func AllTargets 

func AllTargets() []Target

AllTargets returns the known install targets.

func TargetByKey 

func TargetByKey(key string) (Target, bool)

TargetByKey returns the target with the given key.

func (Target) BaseDir 

func (t Target) BaseDir(scope Scope) (string, error)

BaseDir returns the skills base directory for this target and scope (the folder that will contain the promptvm/ skill folder).

func (Target) DestDir 

func (t Target) DestDir(scope Scope) (string, error)

DestDir returns the install folder for this target/scope: <baseDir>/promptvm.

type TrackedTarget 

type TrackedTarget struct {
	Key  string `json:"key"`
	Path string `json:"path"`
}

TrackedTarget records one installed target location.

type Tracker 

type Tracker struct {
	Name        string          `json:"name"`
	Version     int             `json:"version"`
	Checksum    string          `json:"checksum"`
	Status      string          `json:"status"`
	Targets     []TrackedTarget `json:"targets,omitempty"`
	InstalledAt string          `json:"installed_at"`
	// contains filtered or unexported fields
}

Tracker is the on-disk marker recording what the CLI installed. Its presence is what makes first-run auto-install idempotent.

func LoadTracker 

func LoadTracker() (*Tracker, error)

LoadTracker reads the marker. Returns (nil, nil) when absent.

func (*Tracker) Save 

func (t *Tracker) Save() error

Save atomically writes the marker (tmp + rename).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.