skilllib

Documentation

Overview

Package skilllib implements iterion's first-class skill library: a standalone, operator-curated store of Claude-Code-style SKILL.md skills, stored globally (~/.iterion/skills/) with an optional per-project override, and referenced from workflows via the DSL `skills:` field. See ADR-059 and docs/skills-library.md.

The library is the hand-authored/editable half of the "hybride" model; the plugin path (plugin.SynthesizeSkillsManifest) remains the third-party-pack import route. Both mirror into <workspace>/.claude/skills/ at run start via the shared runtime.reconcileSkillFile collision policy.

Index

• Constants
• func ScanFrontmatter(r io.Reader) (name, description string)
• func ValidName(name string) error
• type LibrarySkill
• type Store
  • func LocalStoreForProject(projectStoreDir string) *Store
  • func NewStore(globalDir, projectDir string) *Store
  • func (s *Store) Get(name string) (LibrarySkill, error)
  • func (s *Store) HasProject() bool
  • func (s *Store) List() ([]LibrarySkill, error)
  • func (s *Store) Put(name, body, scope string) error
  • func (s *Store) Remove(name, scope string) error
  • func (s *Store) Resolve(name string) (string, bool)

Constants

const (
	ScopeGlobal  = "global"
	ScopeProject = "project"
)

Scope constants for a library skill's origin layer.

const SkillsDirName = "skills"

SkillsDirName is the leaf directory both the global store (<GlobalIterionDataDir>/skills) and the per-project override (<projectStoreDir>/skills) live under.

Functions

func ScanFrontmatter

func ScanFrontmatter(r io.Reader) (name, description string)

ScanFrontmatter reads leading YAML-ish frontmatter (delimited by `---` lines) from r and returns the `name:` and `description:` fields. It is tolerant of a missing frontmatter block (returns empty strings) and never errors on content — only the caller's file open can fail. This is the single shared parser used by both the skill library and runview's bundle-skill catalog (runview.readSkillFile), so the two never drift.

func ValidName

func ValidName(name string) error

ValidName rejects names that would escape the store dir or collide with the on-disk layout. A library skill name is a single path segment.

Types

type LibrarySkill

type LibrarySkill struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Path        string `json:"-"`     // absolute on-disk path to the SKILL.md / <name>.md
	Scope       string `json:"scope"` // "global" | "project"
	Body        string `json:"body,omitempty"`
}

LibrarySkill is one skill in the library. Name is the canonical on-disk identifier (the directory or file basename) — resolution, removal and DSL references all key on it; a frontmatter `name:` is NOT allowed to override it so List/Resolve stay consistent. Description comes from frontmatter. Body is populated only by Get (List leaves it empty for brevity).

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store is the layered skill library: a required global directory plus an optional per-project override that shadows the global by name. Modeled on pkg/secrets.LayeredGenericSecretStore, minus sealing — skills are not secrets.

func LocalStoreForProject

func LocalStoreForProject(projectStoreDir string) *Store

LocalStoreForProject builds the standard local library: global <GlobalIterionDataDir>/skills plus a per-project <projectStoreDir>/skills override when projectStoreDir is a distinct, non-empty directory (the run's resolved `.iterion` store dir). Pass "" for a global-only store.

func NewStore

func NewStore(globalDir, projectDir string) *Store

NewStore builds a store over an explicit global dir and an optional project dir. projectDir "" (or equal to globalDir) disables the project layer.

func (*Store) Get

func (s *Store) Get(name string) (LibrarySkill, error)

Get returns one skill (resolved project-then-global), including its full body. Returns an error when the name resolves to no file.

func (*Store) HasProject

func (s *Store) HasProject() bool

HasProject reports whether a project override layer is configured.

func (*Store) List

func (s *Store) List() ([]LibrarySkill, error)

List returns every skill across both layers, project shadowing global by name, sorted by name. Descriptions are parsed from frontmatter; bodies are omitted (use Get).

func (*Store) Put

func (s *Store) Put(name, body, scope string) error

Put writes (creates or overwrites) a skill body at the given scope. When a flat <name>.md already exists in that scope it is rewritten in place; otherwise the canonical directory form <name>/SKILL.md is written. Durable (atomic write + fsync).

func (*Store) Remove

func (s *Store) Remove(name, scope string) error

Remove deletes a skill at the given scope (whichever on-disk form exists). Returns an error when the skill does not exist in that scope.

func (*Store) Resolve

func (s *Store) Resolve(name string) (string, bool)

Resolve returns the on-disk path for name (project override preferred over global) and whether it exists. Used by the runtime mirror.