skills

package
v0.50.1 Latest Latest
Warning

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

 Go to latest Published: Jun 23, 2026 License: AGPL-3.0 Imports: 30 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	SkillStatusDraft      = "draft"
	SkillStatusActive     = "active"
	SkillStatusDeprecated = "deprecated"
)

Variables

View Source 
var ErrNoUpgradeSource = errors.New("skill was not installed from a source")

ErrNoUpgradeSource indicates a skill has no recorded install source to re-fetch from (e.g. it was created by hand rather than installed).

Functions

func BuildPromptSection 

func BuildPromptSection(ctx context.Context, build pkgplugins.SystemPromptContext) (pkgplugins.SystemPromptSection, error)

func FetchSkillFiles 

func FetchSkillFiles(ctx context.Context, source string) (skillName string, files map[string]string, version string, cleanup func(), err error)

FetchSkillFiles resolves source, finds the skill directory, and returns the skill name, a map of file paths (relative to the skill root) → content, and the installed version (the git ref/commit for git sources, the clawhub version for clawhub sources, empty for local). cleanup is a no-op for shared-cache git and local sources; for an authenticated GitHub clone it removes the temp dir.

For github.com sources, a token carried via WithGitHubToken authenticates the clone (via BasicAuth into a private temp dir) so private repos install and anonymous rate limits are avoided.

Supported source formats:

  • clawhub:<slug>[@version] — download from clawhub.ai
  • owner/repo@skill-name — GitHub shorthand (via mcphub)
  • GitHub/GitLab URLs — cloned via git
  • local paths — read from filesystem

func GitHubSource added in v0.49.0 

func GitHubSource(source string) bool

GitHubSource reports whether source resolves to a github.com repository, which can be authenticated with a user's bound GitHub OAuth token via WithGitHubToken.

func InstallToStore 

func InstallToStore(ctx context.Context, store pkgplugins.SkillStore, source, scope string, userID string, agentID string) (string, error)

InstallToStore fetches a skill from source and stores it in the given SkillStore. scope must be one of "user", "user_agent", or "system_agent". user uses userID; user_agent uses both; system_agent uses agentID. Returns the installed skill name on success.

func IsWritable added in v0.38.0 

func IsWritable(scope string) bool

IsWritable returns whether a skill scope supports write operations.

func ListDirFiles added in v0.38.0 

func ListDirFiles(dir string) ([]string, error)

ListDirFiles walks a directory and returns relative file paths.

func ListProjectSkills 

func ListProjectSkills(root string) ([]pkgplugins.Skill, map[string]string, error)

ListProjectSkills walks {root}/.agents/skills/ and returns skill metadata structs with Scope="project". The second return value maps skill name → skill directory path so callers can read file content off disk for a given project skill.

func ListSystemSkills added in v0.38.0 

func ListSystemSkills(stellaHome string) ([]pkgplugins.Skill, map[string]string, error)

ListSystemSkills walks {stellaHome}/.agents/skills/ and returns skill metadata structs with Scope="system". System skills are extracted from the embedded FS at startup under a system/ subdirectory, so this walks recursively.

func NormalizeSkillStatus 

func NormalizeSkillStatus(status string) string

func ValidateSkillName 

func ValidateSkillName(name, parentDirName string) []string

ValidateSkillName checks a skill name against the Agent Skills spec.

func WithGitHubToken added in v0.49.0 

func WithGitHubToken(ctx context.Context, token string) context.Context

WithGitHubToken returns ctx carrying a GitHub access token used to authenticate clones of github.com skill sources. An empty token is a no-op, leaving clones anonymous.

func WithProjectRoot 

func WithProjectRoot(ctx context.Context, projectRoot string) context.Context

Types

type CatalogSkill added in v0.47.0 

type CatalogSkill struct {
	Slug         string
	Name         string
	Summary      string
	Version      string    // empty when unknown
	Downloads    *int      // nil in search mode (upstream search has no stats)
	Installs     *int      // nil in search mode
	UpdatedAt    time.Time // zero when unknown
	AuthorHandle string    // empty in browse mode (upstream list has no owner)
	AuthorImage  string
}

CatalogSkill is one marketplace row from the ClawHub registry.

func BrowseCatalog added in v0.47.0 

func BrowseCatalog(ctx context.Context, q string, limit int, pageToken string) (items []CatalogSkill, nextPageToken string, err error)

BrowseCatalog returns popular skills when q is empty (paginated via the opaque pageToken) and search results when q is set (no pagination).

type CatalogSkillDetail added in v0.47.0 

type CatalogSkillDetail struct {
	Slug    string
	Name    string
	Summary string
	Version string
	Readme  string   // SKILL.md content, empty when absent
	Files   []string // relative file paths, sorted
}

CatalogSkillDetail is a single marketplace skill enriched with its README and file list, fetched by downloading the skill archive from ClawHub.

func FetchCatalogDetail added in v0.47.0 

func FetchCatalogDetail(ctx context.Context, slug string) (CatalogSkillDetail, error)

FetchCatalogDetail resolves a skill's metadata and downloads its archive to surface the README (SKILL.md) and file list for a marketplace detail view.

type ResolvedSkill added in v0.38.0 

type ResolvedSkill struct {
	pkgplugins.Skill
	Dir string // absolute path on disk; empty for DB-only skills without disk sync
}

ResolvedSkill is a skill with its filesystem directory (if applicable).

type Service added in v0.38.0 

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

Service provides unified skill resolution across all 4 levels (project, user, agent, system). Both the CLI tool and HTTP server use this to avoid duplicating the merge/resolve logic.

func NewService added in v0.38.0 

func NewService(store pkgplugins.SkillStore, stellaHome string) *Service

func (*Service) ListFiles added in v0.38.0 

func (s *Service) ListFiles(ctx context.Context, name string, vc pkgplugins.SkillViewContext, projectRoot string) ([]string, string, error)

ListFiles returns file paths for a resolved skill.

func (*Service) ListMerged added in v0.38.0 

func (s *Service) ListMerged(ctx context.Context, vc pkgplugins.SkillViewContext, projectRoot string) ([]ResolvedSkill, error)

ListMerged returns all visible skills across project, DB, and system levels, deduplicated by name with priority: project > DB (user/agent) > system. It uses the store's default List query which filters deprecated/disabled skills.

func (*Service) ListMergedWithDB added in v0.38.0 

func (s *Service) ListMergedWithDB(dbSkills []pkgplugins.Skill, projectRoot string) []ResolvedSkill

ListMergedWithDB merges the given DB skills with FS skills. Use this when the caller needs a different DB query (e.g. including disabled skills).

func (*Service) LoadFile added in v0.38.0 

func (s *Service) LoadFile(ctx context.Context, name, path string, vc pkgplugins.SkillViewContext, projectRoot string) (content string, skillDir string, err error)

LoadFile loads a file from a skill resolved by name. Returns the file content and the skill's directory path (if on disk).

func (*Service) Resolve added in v0.38.0 

func (s *Service) Resolve(ctx context.Context, name string, vc pkgplugins.SkillViewContext, projectRoot string) (*ResolvedSkill, error)

Resolve finds a skill by name across all 4 levels, honoring the scope precedence: project > user_agent > user > system_agent > system. Project (filesystem) wins outright; DB skills (which already rank user_agent > user > system_agent > system among themselves) shadow filesystem system skills.

func (*Service) ResolveScoped added in v0.38.0 

func (s *Service) ResolveScoped(ctx context.Context, name, scope string, vc pkgplugins.SkillViewContext, projectRoot string) (*ResolvedSkill, error)

ResolveScoped finds a skill by name in a specific scope, for management (get/update/delete/file) operations. Unlike Resolve it never falls through to another scope, and it matches by row ownership rather than runtime visibility so it also finds drafts, disabled (knowledge) entries, and DB-backed system skills that the effective Resolve query filters out.

type SkillDirView added in v0.49.0 

type SkillDirView struct {
	Isolated bool
	// SystemSkillsHost/View map the system skills dir specifically (not all of
	// STELLA_HOME): only that subtree is mounted, so a broad STELLA_HOME mapping
	// would wrongly swallow the sibling users/ and agents/ trees nested under it.
	SystemSkillsHost string
	SystemSkillsView string
	// AgentSkillsHost/View map the admin-managed agent-bound (system_agent) skills
	// dir, mounted at its own fixed path (/opt/stella/agent-skills) since it lives
	// in the user-independent agent definition tree, outside the two roots.
	AgentSkillsHost string
	AgentSkillsView string
	// SystemDBSkillsHost/View map the DB-installed system skills dir (a sibling of
	// the shipped built-ins under STELLA_HOME), mounted at its own fixed path
	// (/opt/stella/db-skills); the built-ins map via SystemSkillsHost/View.
	SystemDBSkillsHost string
	SystemDBSkillsView string
	// UserData and Workspace are full binds, so their whole root maps (this lets
	// project skills under <workspace>/projects/<id>/.agents/skills map too).
	UserDataHost  string
	UserDataView  string
	WorkspaceHost string
	WorkspaceView string
}

SkillDirView remaps a host skill directory to the path the agent sees inside the sandbox, so an emitted <skill_dir> is usable in bash and never leaks a host path. The zero value is identity (host paths emitted) for host-execution and non-sandbox callers. For an isolating backend, set Isolated and the host→view root pairs; a skill dir under no known root is then omitted rather than leaked.

type Tool 

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

func NewTool 

func NewTool(store pkgplugins.SkillStore, stellaHome, projectRoot string) *Tool

func (*Tool) Definition 

func (t *Tool) Definition() tools.Definition

func (*Tool) Execute 

func (t *Tool) Execute(ctx context.Context, args map[string]any) (string, error)

func (*Tool) WithSkillDirView added in v0.49.0 

func (t *Tool) WithSkillDirView(v SkillDirView) *Tool

WithSkillDirView sets how host skill directories are remapped to the model-visible paths the agent sees inside the sandbox. The default (zero value) emits host paths, which is correct for host-execution and non-sandbox callers.

func (*Tool) WithSkillDiskLayout added in v0.49.0 

func (t *Tool) WithSkillDiskLayout(l coreskills.SkillDiskLayout) *Tool

WithSkillDiskLayout sets where DB-backed skills live on disk, by scope. The emitted <skill_dir> for a DB skill comes from here, so it must match the dirs the disk-mirroring writer used. The zero value emits no dir for DB skills.

type UpgradeResult added in v0.49.0 

type UpgradeResult struct {
	Updated         bool   // true when the skill's files/version changed
	Version         string // the version now installed
	PreviousVersion string // the version before the upgrade
}

UpgradeResult reports the outcome of re-fetching a skill from its source.

func UpgradeInStore added in v0.49.0 

func UpgradeInStore(ctx context.Context, store pkgplugins.SkillStore, skillID string, metadata json.RawMessage) (UpgradeResult, error)

UpgradeInStore re-fetches the skill identified by skillID from the install source recorded in its metadata and, when the resolved version differs from the stored one, replaces the skill's files and refreshes its metadata from the new SKILL.md. An unchanged version is a no-op (Updated=false), so this doubles as a check: callers get "already up to date" without a second round-trip.

For github.com sources a token carried via WithGitHubToken authenticates the fetch, exactly as during install. metadata is the skill's current metadata blob; its created-at and source are preserved while version is bumped.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.