active

Documentation

Overview

Package active manages the project active-skill layer: the per-skill entry at .agents/skills/<name> that links into the content store and is the single source of truth every agent target derives from.

The three layers gskill maintains are:

.gskill/store/<algo>/<hash>   immutable canonical content (one physical copy)
          ▲ symlink (copy fallback)
.agents/skills/<name>          active project skill (one per installed skill)
          ▲ symlink (copy fallback)
.<agent>/skills/<name>         per-agent targets (claude, codex, cursor, …)

The active layer holds no independent copy of the content: it links into the store, so adding an agent is one cheap link and a skill shared by N agents still exists exactly once on disk. The active layer is gitignored and regenerated by `gskill sync` from the committed manifest + lockfile.

Index

• func Dir(root string) string
• func EnsureActive(root, name, storePath, storeRoot string) (string, error)
• func List(root string) ([]string, error)
• func Path(root, name string) string
• func Rel(name string) string
• func Remove(root, name string) error
• type Health
  • func HealthOf(root, name, storePath string) (Health, error)

Functions

func Dir

func Dir(root string) string

Dir returns the active-skills container directory under root.

func EnsureActive

func EnsureActive(root, name, storePath, storeRoot string) (string, error)

EnsureActive makes the active entry for name resolve to storePath, preferring a symlink and falling back to a copy where symlinks are unsupported. It is idempotent (an entry already linking to storePath is left untouched) and re-points a stale gskill-managed symlink (one resolving into storeRoot) after a content update. It NEVER destroys foreign content: a symlink resolving outside storeRoot, or a real directory whose content does not match the store, fails closed and is left intact (FR-029/FR-030).

func List

func List(root string) ([]string, error)

List returns the names of gskill-managed active entries (symlinks) under root.

func Path

func Path(root, name string) string

Path returns the active entry path for a skill name under root.

func Rel

func Rel(name string) string

Rel returns the project-relative active entry path for a skill name.

func Remove

func Remove(root, name string) error

Remove deletes a gskill-managed active entry (a symlink) for name. It is a no-op when the entry is absent, and it never deletes a non-symlink path, so a foreign directory occupying the name is left intact.

Types

type Health

type Health string

Health classifies the state of an active entry relative to its expected store target.

const (
	// HealthOK means the entry is a symlink resolving to the expected store path.
	HealthOK Health = "ok"
	// HealthMissing means no entry exists.
	HealthMissing Health = "missing"
	// HealthBroken means the entry is a symlink whose target does not exist.
	HealthBroken Health = "broken"
	// HealthForeign means a non-symlink path occupies the entry (not gskill-managed).
	HealthForeign Health = "foreign"
	// HealthWrongStore means the entry is a symlink into the store but at the
	// wrong content path (e.g. stale after a content update).
	HealthWrongStore Health = "wrong-store-target"
)

Active-entry health states.

func HealthOf

func HealthOf(root, name, storePath string) (Health, error)

HealthOf reports the active entry's state relative to the expected storePath.