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
- Variables
- func Apply(steps []Step) error
- func Command(verb string, copies []Copy, force bool) string
- func Dirs(copies []Copy) string
- func Hash(files Files) string
- func Refs(root string) (map[string][]byte, error)
- func Root() (string, error)
- func Short(path string) string
- func Write(dir string, files Files) error
- type Action
- type Agent
- type Copy
- type Dest
- type Files
- type Marker
- type Scope
- type State
- type Step
Constants ¶
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.
const Name = "proximo"
Name is the Skill's directory name, under every agent's `skills/`.
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 ¶
var Agents = []Agent{Claude, Codex}
Agents is every agent proximo knows how to install for, in the order they are reported.
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 Command ¶
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 Hash ¶
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 ¶
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 ¶
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 ¶
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.
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 DecideRemove ¶
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.
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.
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 ¶
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.
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.
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.
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 ¶
Forcible reports whether --force may act on a copy in this state, which is what decides whether a report has an override to offer.