skills

package
v0.107.39 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const (
	PackMaxDepth  = 4
	PackMaxDirs   = 5000
	PackMaxSkills = 200
)

Skill packs. A top-level directory of a skills root that has no SKILL.md of its own but holds SKILL.md files further down (a cloned repository of skills, for example) is a skill pack. The LiveAgent desktop applies the same rule, so the limits and orderings below are part of the contract:

  • The pack is walked breadth-first, at most PackMaxDepth directory levels below the pack directory, visiting at most PackMaxDirs directories and accepting at most PackMaxSkills skills.
  • Dot-directories, the names in packSkipDirs and symlinks that resolve outside the skills root are not entered. Skill directories are entered too: a router skill may hold child skills.
  • Every directory with a SKILL.md whose frontmatter has a name and a description is a skill named by that frontmatter name (lenient checks: the name need not match the directory, see lenientName).
  • Within a pack the shallowest skill keeps a name, ties going to the byte-wise smaller BaseDir; the others are shadowed. Across the root a top-level skill beats a pack skill, and between packs the pack whose directory name sorts first wins.
View Source
const PromptPackBudget = 12 << 10

PromptPackBudget bounds, in bytes, how much of the <available_skills> block one skill pack may take. A pack over budget lists its router (its shallowest skill) in full and the rest compactly; see writePack.

Variables

This section is empty.

Functions

func DefaultDirs

func DefaultDirs() []string

func DirsFor added in v0.103.0

func DirsFor(project string) []string

func ForeignDirs

func ForeignDirs() []string

func PromptBlock

func PromptBlock(sk []Skill) string

func ScanDetailed

func ScanDetailed(dirs ...string) ([]Skill, []ScanProblem)

ScanDetailed returns the skills found in dirs and the SKILL.md files that could not be used. Shadowed skill-pack copies are left out; see ScanAll.

func TruncateDescription added in v0.107.28

func TruncateDescription(s string, n int) string

TruncateDescription shortens s to at most n runes, ending with "…" when it cut something. Whitespace runs collapse to single spaces first.

func ValidName

func ValidName(name string) bool

Types

type ClawHubCard added in v0.107.0

type ClawHubCard struct {
	Slug          string `json:"slug"`
	DisplayName   string `json:"displayName"`
	Summary       string `json:"summary"`
	LatestVersion string `json:"latestVersion,omitempty"`
	Downloads     int64  `json:"downloads"`
	Stars         int64  `json:"stars"`
	OwnerHandle   string `json:"ownerHandle,omitempty"`
	WebURL        string `json:"webUrl,omitempty"`
	DownloadURL   string `json:"downloadUrl"`
}

type DeleteResult added in v0.107.0

type DeleteResult struct {
	Name   string `json:"name"`
	Target string `json:"target"`
}

type ExternalScan added in v0.107.0

type ExternalScan struct {
	Tool    string          `json:"tool"`
	RootDir string          `json:"rootDir"`
	Exists  bool            `json:"exists"`
	Skills  []ExternalSkill `json:"skills"`
	Errors  []string        `json:"errors"`
}

type ExternalSkill added in v0.107.0

type ExternalSkill struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	BaseDir     string `json:"baseDir"`
	SkillFile   string `json:"skillFile"`
	Pack        string `json:"pack,omitempty"`
}

type InstallResult added in v0.107.0

type InstallResult struct {
	Name      string `json:"name"`
	Target    string `json:"target"`
	Backup    string `json:"backup,omitempty"`
	SkillFile string `json:"skillFile"`
	// Pack is set when the source had no SKILL.md at its root and was
	// installed as a skill pack named Pack; Skills counts the pack's skills and
	// SkillFile is its router (shallowest skill).
	Pack   string `json:"pack,omitempty"`
	Skills int    `json:"skills,omitempty"`
}

type InvalidSkill added in v0.107.0

type InvalidSkill struct {
	Path  string `json:"path"`
	Error string `json:"error"`
}

type Job added in v0.107.0

type Job struct {
	JobID           string          `json:"jobId"`
	Phase           string          `json:"phase"`
	Source          string          `json:"source"`
	DownloadedBytes int64           `json:"downloadedBytes"`
	TotalBytes      *int64          `json:"totalBytes,omitempty"`
	Installed       []InstallResult `json:"installed,omitempty"`
	Error           string          `json:"error,omitempty"`
	StartedAt       int64           `json:"startedAt"`
	UpdatedAt       int64           `json:"updatedAt"`
	FinishedAt      int64           `json:"finishedAt,omitempty"`
	// contains filtered or unexported fields
}

type Manager added in v0.107.0

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

func NewManager added in v0.107.0

func NewManager() (*Manager, error)

func (*Manager) Create added in v0.107.0

func (m *Manager) Create(name, description, body, conflict string, files []map[string]string) (InstallResult, error)

func (*Manager) Delete added in v0.107.0

func (m *Manager) Delete(name string) (DeleteResult, error)

func (*Manager) Effective added in v0.107.0

func (m *Manager) Effective(workdir string) ([]Skill, SkillSettings, error)

Effective returns the skills a backend run advertises for workdir. Skills of the managed root are opt-in: a top-level skill is on when selected by name; a pack skill when its pack is switched on in settings.packs, or, for a pack not listed there, when selected by name. A pack switched off hides all of its skills. Skills of the other scan directories are always on.

func (*Manager) External added in v0.107.0

func (m *Manager) External() []ExternalScan

func (*Manager) Install added in v0.107.0

func (m *Manager) Install(ctx context.Context, source, name, conflict string, meta *SourceMetadata, progress func(int64, int64)) (InstallResult, error)

func (*Manager) List added in v0.107.0

func (m *Manager) List() ([]SkillSummary, []InvalidSkill, error)

List returns the usable skills of the managed root (top-level skills and the pack skills that kept their names) and the SKILL.md files it could not use. ListAll also returns the shadowed pack skills.

func (*Manager) ListAll added in v0.107.28

func (m *Manager) ListAll() (skills, shadowed []SkillSummary, invalid []InvalidSkill, err error)

func (*Manager) Manage added in v0.107.0

func (m *Manager) Manage(ctx context.Context, args map[string]any) (ManagerResponse, error)

func (*Manager) Package added in v0.107.0

func (m *Manager) Package(name string) (PackageResult, error)

func (*Manager) Read added in v0.107.0

func (m *Manager) Read(path string, offset, length int) (string, bool, int, error)

func (*Manager) Root added in v0.107.0

func (m *Manager) Root() string

func (*Manager) SaveSettings added in v0.107.0

func (m *Manager) SaveSettings(workdir string, v SkillSettings) (uint64, error)

func (*Manager) SetHTTPClient added in v0.107.0

func (m *Manager) SetHTTPClient(client *http.Client) error

SetHTTPClient is an explicit fixture/deployment seam. The default transport only accepts HTTPS.

func (*Manager) SetStoreURL added in v0.107.0

func (m *Manager) SetStoreURL(raw string) error

SetStoreURL overrides the ClawHub-compatible registry endpoint for an explicitly configured fixture.

func (*Manager) Settings added in v0.107.0

func (m *Manager) Settings(workdir string) (uint64, SkillSettings, error)

func (*Manager) Validate added in v0.107.0

func (m *Manager) Validate(name string) Validation

type ManagerResponse added in v0.107.0

type ManagerResponse struct {
	Action            string          `json:"action"`
	RootDir           string          `json:"rootDir"`
	Path              string          `json:"path,omitempty"`
	Content           string          `json:"content,omitempty"`
	Truncated         bool            `json:"truncated,omitempty"`
	StartLine         int             `json:"startLine,omitempty"`
	NumLines          int             `json:"numLines,omitempty"`
	Skills            []SkillSummary  `json:"skills,omitempty"`
	Shadowed          []SkillSummary  `json:"shadowed,omitempty"`
	Invalid           []InvalidSkill  `json:"invalid,omitempty"`
	Installed         []InstallResult `json:"installed,omitempty"`
	Created           *InstallResult  `json:"created,omitempty"`
	Validation        *Validation     `json:"validation,omitempty"`
	Package           *PackageResult  `json:"package,omitempty"`
	Deleted           *DeleteResult   `json:"deleted,omitempty"`
	InstallJob        *Job            `json:"installJob,omitempty"`
	ClawhubNextCursor string          `json:"clawhubNextCursor,omitempty"`
	ClawhubResults    []ClawHubCard   `json:"clawhubResults,omitempty"`
	External          []ExternalScan  `json:"external,omitempty"`
	ExternalMCP       []any           `json:"externalMcp,omitempty"`
}

type PackageResult added in v0.107.0

type PackageResult struct {
	Name    string `json:"name"`
	Target  string `json:"target"`
	Archive string `json:"archive"`
}

type ScanProblem

type ScanProblem struct {
	Path string
	Err  string
}

type ScanResult added in v0.107.28

type ScanResult struct {
	// Skills are the usable skills: top-level skills and the pack skills that
	// kept their names, in directory order with each pack's skills shallowest
	// first.
	Skills []Skill
	// Shadowed are pack skills that lost their name to another skill of the
	// same root; ShadowedBy names the winner.
	Shadowed []Skill
	// Problems are SKILL.md files that could not be used and packs that hit a
	// walk limit.
	Problems []ScanProblem
}

ScanResult is everything a scan of skill directories found.

func ScanAll added in v0.107.28

func ScanAll(dirs ...string) ScanResult

ScanAll scans each directory for top-level skills and skill packs. Directories are independent: names are only de-duplicated within one.

type Skill

type Skill struct {
	Name        string
	Description string
	Path        string

	DisableModelInvocation bool

	Warning string

	// Root is the scanned skills directory the skill was found in.
	Root string
	// BaseDir is the skill's directory relative to Root, with forward slashes
	// on every platform: "radare2" for a top-level skill,
	// "reverse-skill/skills/radare2" for one inside a skill pack.
	BaseDir string
	// Pack is the top-level directory of the skill pack that holds the skill;
	// empty for a top-level skill.
	Pack string
	// ShadowedBy is the BaseDir of the skill that kept this skill's name. It is
	// set only on shadowed copies, which ScanAll reports apart from the skills.
	ShadowedBy string
}

func Scan

func Scan(dirs ...string) []Skill

type SkillSettings added in v0.107.0

type SkillSettings struct {
	Enabled    bool     `json:"enabled"`
	Selected   []string `json:"selected"`
	Mode       string   `json:"mode,omitempty"`
	SkillNames []string `json:"skillNames,omitempty"`
	// Packs switches whole skill packs, keyed by pack directory name: true
	// turns on every skill of the pack, false turns all of them off even when
	// selected by name. A pack not listed follows Selected skill by skill.
	Packs map[string]bool `json:"packs,omitempty"`
}

type SkillSummary added in v0.107.0

type SkillSummary struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Target      string          `json:"target"`
	SkillFile   string          `json:"skillFile"`
	BaseDir     string          `json:"baseDir"`
	BuiltIn     bool            `json:"builtIn"`
	InstalledAt int64           `json:"installedAt,omitempty"`
	Source      *SourceMetadata `json:"source,omitempty"`
	// Pack is the skill pack directory holding the skill; empty for a
	// top-level skill. BaseDir is then "<pack>/<path inside the pack>".
	Pack string `json:"pack"`
	// Shadowed is true for a pack skill whose name another skill kept;
	// ShadowedBy is that skill's baseDir. Shadowed skills are never active.
	Shadowed   bool   `json:"shadowed"`
	ShadowedBy string `json:"shadowedBy,omitempty"`
}

type SourceMetadata added in v0.107.0

type SourceMetadata struct {
	Registry               string `json:"registry"`
	Slug                   string `json:"slug"`
	OwnerHandle            string `json:"ownerHandle,omitempty"`
	Version                string `json:"version,omitempty"`
	OriginalName           string `json:"originalName,omitempty"`
	NormalizedName         string `json:"normalizedName,omitempty"`
	CompatibilityTransform string `json:"compatibilityTransform,omitempty"`
}

type Validation added in v0.107.0

type Validation struct {
	Name   string   `json:"name"`
	Target string   `json:"target"`
	OK     bool     `json:"ok"`
	Errors []string `json:"errors"`
	// Pack is set when Name is a skill pack or a skill inside one; such
	// skills get the lenient pack checks. Warnings lists a pack's unusable
	// SKILL.md files and walk limits.
	Pack     string   `json:"pack,omitempty"`
	Warnings []string `json:"warnings,omitempty"`
}

Jump to

Keyboard shortcuts

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