skill

package
v0.16.0 Latest Latest
Warning

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

Go to latest
Published: Oct 2, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package skill installs the agent Skill proximo ships, and reports how every installed copy stands against the binary that would write it.

The Skill is compiled into the CLI, so its version is the CLI's version: a skill describing labels the installed binary does not implement is worse than no skill, because it is confidently wrong. A copy this package wrote carries a marker file beside its SKILL.md; the absence of that marker is itself the answer — the copy came from a channel proximo does not manage, and is left alone. See docs/adr/0005-the-agent-skill-ships-in-the-cli.md.

Index

Constants

View Source
const MarkerName = ".proximo-skill.json"

MarkerName is the side file written beside the installed SKILL.md. Its presence marks a Managed copy; its contents say which version wrote the copy and what the copy contained when it was written.

View Source
const Name = "proximo"

Name is the Skill's directory name, under every agent's `skills/`.

View Source
const Site = "https://filippolmt.github.io/proximo/"

Site is the published documentation. Nothing in the Skill may use a repository-relative link out of the Skill: a globally installed copy has no `docs/` beside it, so every reference out is an absolute URL.

Variables

View Source
var Agents = []Agent{Claude, Codex}

Agents is every agent proximo knows how to install for, in the order they are reported.

View Source
var ErrNoRepo = errors.New("not inside a git repository, so there is no project to install into (use --scope global)")

ErrNoRepo is returned when project scope was asked for outside a git repository. It is deliberately an error and never a fallback to global: a copy silently written somewhere else is a copy nobody can find.

Functions

func Apply

func Apply(steps []Step) error

Apply performs the writing steps, leaving every other one alone.

func Command

func Command(verb string, copies []Copy, force bool) string

Command is the `proximo skill <verb>` invocation that reaches these copies. Both subcommands default to project scope, so a set that lives only under the developer's home must carry --scope global — otherwise the command would act somewhere else entirely and leave these exactly as they were.

A set spanning both scopes takes two runs: this names the project one, and whatever reports next names what is left. Naming one command that reaches half the set is the alternative, and it is worse.

func Dirs

func Dirs(copies []Copy) string

Dirs renders the copies a report is about, in the paths a developer types.

func Hash

func Hash(files Files) string

Hash digests a Skill tree: paths and contents both, in sorted order, so two runs on the same content always agree and a renamed file is a different tree.

func Refs

func Refs(root string) (map[string][]byte, error)

Refs regenerates every generated block in the Skill source under root, returning the full new content of each file that carries one, by path. Nothing is written: the caller decides whether this is a check or an update.

func Root

func Root() (string, error)

Root resolves the repository proximo is being run from, walking up from the working directory. It asks the filesystem rather than git: the answer is a directory containing `.git`, which needs no subprocess and no git on PATH.

func Short

func Short(path string) string

Short renders a path the way a developer reads it back — and types it when they go and look: relative to the working directory when it is under it, so a project copy reads as `.claude/skills/proximo`, exactly as it appears in `git status`.

Never from the home directory or an ancestor of it, though. Standing in `$HOME`, a global copy would render as `.claude/skills/proximo` — the shape of a project copy, beside a Remedy naming `--scope global`; standing in `/`, it would render as a bare `home/you/…` that resolves nowhere else. Both are `~/.claude/skills/proximo` instead, which is true wherever it is read.

func Write

func Write(dir string, files Files) error

Write installs the Skill into dir and marks it Managed. The marker is written last: a run interrupted midway leaves a copy with no marker, which the next run treats as unmanaged and reports rather than a copy it silently trusts.

Types

type Action

type Action string

Action is what a run decided to do about one copy.

const (
	// Install writes a copy where there was none.
	Install Action = "install"
	// Refresh brings an untouched Managed copy level with this binary.
	Refresh Action = "refresh"
	// Overwrite replaces an edited copy. Only --force produces it.
	Overwrite Action = "overwrite"
	// Keep leaves a copy that is already level with this binary.
	Keep Action = "keep"
	// SkipModified leaves an edited copy alone and reports it.
	SkipModified Action = "skip (edited locally)"
	// SkipUnmanaged leaves a copy proximo did not write alone.
	SkipUnmanaged Action = "skip (not installed by proximo)"
	// Delete removes a Managed copy that is intact.
	Delete Action = "remove"
)

func Decide

func Decide(c Copy, force bool) Action

Decide maps a copy's state to the action an install would take.

func DecideRemove

func DecideRemove(c Copy, force bool) Action

DecideRemove maps a copy's state to the action an uninstall would take. Uninstall keeps the promise that install is reversible, without extending it into deleting work proximo did not write.

func (Action) Touches

func (a Action) Touches() bool

Touches reports whether an action changes the filesystem. Removing is one of them, which is why it is not called Writes.

type Agent

type Agent string

Agent is a coding agent that reads the Skill. Both read the identical format, which is why there is one Skill and not one per agent.

const (
	// Claude is Claude Code, whose skills live under `.claude/skills`.
	Claude Agent = "claude"
	// Codex is OpenAI Codex, whose skills live under `$CODEX_HOME/skills`.
	Codex Agent = "codex"
)

func Detected

func Detected() []Agent

Detected returns the agents present here, so `skill install` with no --agent installs for what is actually used. An agent counts as present when it has a configuration directory at either scope, or its command is on PATH: any one of the three means somebody runs it here.

The project scope is consulted as well as the home one, because the default install *is* project-scoped: a repository that already carries `.claude/` is the plainest evidence the agent is used, and refusing on a machine whose home has none would ignore the very directory about to be written to.

func ParseAgents

func ParseAgents(flag string) ([]Agent, error)

ParseAgents resolves the --agent flag. An empty value means every agent detected on this host, which is the default; "all" means both, detected or not, for a developer setting a machine up before installing the agent.

type Copy

type Copy struct {
	Dest
	State State
	// Version is what the marker records, empty when there is no marker.
	Version string
}

Copy is one destination and what is actually there.

func Inspect

func Inspect(d Dest, want string) Copy

Inspect reports what is at a destination, given the digest of the Skill this binary would write.

func Survey

func Survey() ([]Copy, error)

Survey reports every copy proximo can see: both agents, both scopes, minus the project scope when there is no repository to look in. It is what the `agent-skill` Check reads and what auto-update works from.

type Dest

type Dest struct {
	Agent Agent
	Scope Scope
	// Dir is the Skill's own directory — the one holding SKILL.md.
	Dir string
}

Dest is one place the Skill can live.

func Resolve

func Resolve(a Agent, s Scope) (Dest, error)

Resolve returns the destination for one agent at one scope.

type Files

type Files map[string][]byte

Files is the Skill's content, by path relative to the Skill directory.

func Embedded

func Embedded() (Files, error)

Embedded returns the Skill compiled into this binary.

type Marker

type Marker struct {
	// Version is the CLI that wrote the copy.
	Version string `json:"version"`
	// Hash is a digest of what it wrote, so a later run can tell a copy it may
	// refresh from one somebody has edited.
	Hash string `json:"hash"`
}

Marker is the side file's content.

type Scope

type Scope string

Scope is where a copy is written: into the repository, where a team shares one answer, or into the user's home, where it follows the developer.

const (
	// Project is the repository proximo is being run from. A write at this
	// scope produces a tracked diff, which is announced rather than made
	// quietly.
	Project Scope = "project"
	// Global is the agent's per-user configuration directory.
	Global Scope = "global"
)

func ParseScope

func ParseScope(flag string) (Scope, error)

ParseScope resolves the --scope flag.

type State

type State string

State is how an installed copy stands against the Skill in this binary.

const (
	// Absent means nothing is installed at the destination.
	Absent State = "absent"
	// Current means a Managed copy matching this binary, untouched.
	Current State = "current"
	// Stale means a Managed copy, untouched, written by another version.
	Stale State = "stale"
	// Modified means a Managed copy whose content no longer matches what
	// proximo wrote. It is never overwritten without --force.
	Modified State = "modified"
	// Unmanaged means a copy with no marker: a marketplace install, or one
	// made by an agent's own skill-installer. proximo neither updates nor
	// removes it.
	Unmanaged State = "unmanaged"
)

func (State) Forcible

func (s State) Forcible() bool

Forcible reports whether --force may act on a copy in this state, which is what decides whether a report has an override to offer.

func (State) Managed

func (s State) Managed() bool

Managed reports whether proximo wrote this copy and can therefore speak for its version.

func (State) Reason

func (s State) Reason() string

Reason says why a copy in this state is left alone, or "" for a state that is not.

type Step

type Step struct {
	Copy
	Action Action
}

Step is one copy and what will be done to it.

func Plan

func Plan(dests []Dest, force bool) ([]Step, error)

Plan pairs each destination with the action an install would take.

func PlanRemove

func PlanRemove(dests []Dest, force bool) ([]Step, error)

PlanRemove pairs each destination with the action an uninstall would take.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL