Documentation
¶
Index ¶
- Variables
- func AddSkillToLock(lock *SkillLock, installName string, entry LockEntry)
- func AgentSkillsDir(agent AgentType, global bool, cwd string) (string, error)
- func CanonicalSkillsDir(global bool, cwd string) (string, error)
- func ClaudeHome() (string, error)
- func CodexHome() (string, error)
- func FetchGitHubSkillFolderHash(ctx context.Context, ownerRepo string, skillPath string, token string) (string, error)
- func GetGitHubToken() string
- func HomeDir() (string, error)
- func Init(opts InitOptions) (string, error)
- func IsUniversalAgent(agent AgentType) (bool, error)
- func RemoveSkillFromLock(lock *SkillLock, installName string)
- func SkillLockPath() (string, error)
- func SkillsAPIURL() string
- func WriteSkillLock(lock *SkillLock) error
- func XDGConfigHome() (string, error)
- type AddOptions
- type AddResult
- type AgentConfig
- type AgentType
- type GetOptions
- type GetResult
- type InitOptions
- type InstallMode
- type InstalledSkill
- type ListOptions
- type ListedSkill
- type LockEntry
- type RemoveOptions
- type RemoveResult
- type SearchResult
- type Skill
- func DiscoverSkills(baseDir string, fullDepth bool) ([]Skill, error)
- func FetchDirectSkillToDir(ctx context.Context, skillURL string) (dir string, skill Skill, installName string, err error)
- func FetchWellKnownSkillToDir(ctx context.Context, resolvedBase string, entry WellKnownSkillEntry) (dir string, skill Skill, installName string, err error)
- func ParseSkillMarkdown(content string) (Skill, error)
- type SkillLock
- type SkillSource
- type SkillSourceType
- type UpdateCheck
- type WellKnownIndex
- type WellKnownSkillEntry
Constants ¶
This section is empty.
Variables ¶
var ( ErrSourceRequired = errors.New("source is required") ErrAgentDiscoveryRequired = errors.New("target dirs are required when agent discovery is disabled") ErrNoTargetDirs = errors.New("no target dirs specified") ErrNoSkillsFound = errors.New("no skills found") ErrNoSkillsSpecified = errors.New("no skills specified") ErrSkillNameRequired = errors.New("skill name is required") ErrMultipleSkills = errors.New("multiple skills found; specify --skill or --yes") ErrMultipleWellKnown = errors.New("multiple well-known skills found; specify --skill or --yes") ErrUnsupportedSourceType = errors.New("unsupported source type") ErrUnknownInstallMode = errors.New("unknown install mode") ErrUnrecognizedSource = errors.New("unrecognized source format") ErrMissingFrontmatter = errors.New("missing frontmatter") ErrMissingName = errors.New("frontmatter missing name") ErrMissingDescription = errors.New("frontmatter missing description") ErrHomeNotFound = errors.New("home directory not found") ErrNoWellKnownIndex = errors.New("no well-known skills index found") ErrUnsafeFilePath = errors.New("unsafe file path in well-known index") ErrSkillAlreadyExists = errors.New("SKILL.md already exists") ErrSkillNotFound = errors.New("skill not found") )
Functions ¶
func AddSkillToLock ¶
func ClaudeHome ¶
func GetGitHubToken ¶
func GetGitHubToken() string
func Init ¶
func Init(opts InitOptions) (string, error)
Init creates a SKILL.md template on disk and returns the created file path.
By default it writes "SKILL.md" in the working directory. If opts.Name is provided, it writes "<dir>/<name>/SKILL.md". If opts.Dir is provided, it is used as the base directory instead of the current working directory.
func IsUniversalAgent ¶
func RemoveSkillFromLock ¶
func SkillLockPath ¶
func SkillsAPIURL ¶
func SkillsAPIURL() string
func WriteSkillLock ¶
func XDGConfigHome ¶
Types ¶
type AddOptions ¶
type AddOptions struct {
// Source is the install source string (local dir, git repo reference, direct URL,
// or a well-known index URL).
Source string
// Dirs are explicit target directories to install into. When provided, agent discovery is
// bypassed and Add installs directly to these directories.
Dirs []string
// Global installs into the global skills locations rather than project-local ones.
// When agent discovery is enabled, global installs may also be tracked in the lock file
// for future update checks.
Global bool
// Agents is an optional allowlist of agent types to install for. When empty and agent
// discovery is enabled, installed agents may be auto-detected.
Agents []AgentType
// Skills selects which skills to install from a multi-skill source. Entries may match
// either the skill folder name or the parsed skill name. "*" selects all discovered skills.
Skills []string
// ListOnly discovers and returns available skills without installing anything.
ListOnly bool
// Yes enables non-interactive defaults when a choice is required (for example, when a
// source contains multiple skills and no explicit selection was provided).
Yes bool
// All installs all discovered skills. In Add, this implies Yes and sets Skills to "*".
All bool
// FullDepth enables deep scanning for SKILL.md files within the source directory tree.
FullDepth bool
// Mode controls how skill files are installed (for example, via symlinks or copying).
Mode InstallMode
// EnableAgentDiscovery enables deriving target directories from the canonical skills dir
// and agent-specific skills dirs when Dirs is not provided.
EnableAgentDiscovery bool
}
type AddResult ¶
type AddResult struct {
Available []Skill
Installed []InstalledSkill
}
func Add ¶
func Add(ctx context.Context, opts AddOptions) (AddResult, error)
Add installs skills from opts.Source and returns what is available and/or installed.
The source may be a local directory, a git repository reference, a direct URL, or a well-known skills index. Behavior is controlled by opts:
- If opts.ListOnly is true, the function only discovers and returns skills (no install).
- If opts.All is true, it implies non-interactive mode and installs all discovered skills.
- If opts.Mode is empty, it defaults to symlink-based installation.
- If opts.Dirs is provided, it installs into those directories directly and skips agent discovery.
- Otherwise, agent discovery must be enabled and target directories are derived from the canonical skills dir plus per-agent skills dirs (agents may be auto-detected when omitted).
When installing globally with agent discovery enabled, Add also records entries in the skill lock file so CheckUpdates/Update can detect and apply future updates for supported sources.
type AgentConfig ¶
type AgentConfig struct {
Name AgentType
DisplayName string
ProjectSkillsDir string
GlobalSkillsDir string
ShowInUniversal bool
DetectProjectPath string
DetectGlobalPath string
}
func AgentConfigFor ¶
func AgentConfigFor(agent AgentType) (AgentConfig, error)
type AgentType ¶
type AgentType string
func AllAgentTypes ¶
func AllAgentTypes() []AgentType
func DetectInstalledAgents ¶
type GetOptions ¶
type GetOptions struct {
// Dirs are explicit directories to search. When provided, agent discovery is bypassed and
// Get searches only these directories.
Dirs []string
// Skill is the install name of the skill to load.
Skill string
// Global searches the global install locations rather than project-local ones.
Global bool
// Agents is an optional allowlist of agent types to search. When empty and agent discovery
// is enabled, installed agents may be auto-detected.
Agents []AgentType
// EnableAgentDiscovery enables deriving target directories from the canonical skills dir
// and agent-specific skills dirs when Dirs is not provided.
EnableAgentDiscovery bool
}
type GetResult ¶
func Get ¶
func Get(opts GetOptions) (GetResult, error)
Get returns the full content and metadata of an installed skill by name.
If opts.Dirs is provided, it searches only those directories. Otherwise, agent discovery must be enabled and Get searches the canonical skills directory first and then per-agent skills directories (filtered by opts.Agents when provided).
type InitOptions ¶
type InstallMode ¶
type InstallMode string
const ( InstallModeSymlink InstallMode = "symlink" InstallModeCopy InstallMode = "copy" )
type InstalledSkill ¶
type ListOptions ¶
type ListOptions struct {
// Dirs are explicit directories to list install names from. When provided, agent discovery
// is bypassed and List reads only these directories.
Dirs []string
// Global lists from the global install locations rather than project-local ones.
Global bool
// Agents is an optional allowlist of agent types to list for. When empty and agent
// discovery is enabled, installed agents may be auto-detected.
Agents []AgentType
// EnableAgentDiscovery enables deriving target directories from the canonical skills dir
// and agent-specific skills dirs when Dirs is not provided.
EnableAgentDiscovery bool
}
type ListedSkill ¶
type ListedSkill struct {
InstallName string
Name string
Description string
Global bool
Agents []AgentType
}
func List ¶
func List(opts ListOptions) ([]ListedSkill, error)
List returns installed skills.
If opts.Dirs is provided, it lists install names from those directories directly. Otherwise, agent discovery must be enabled and List scans the canonical skills directory plus per-agent skills directories (filtered by opts.Agents when provided).
type LockEntry ¶
type LockEntry struct {
Source SkillSource `json:"source"`
SourceType string `json:"source_type"`
SourceURL string `json:"source_url"`
SkillPath string `json:"skill_path,omitempty"`
SkillFolderHash string `json:"skill_folder_hash,omitempty"`
InstalledAt time.Time `json:"installed_at"`
UpdatedAt time.Time `json:"updated_at"`
}
func (*LockEntry) UnmarshalJSON ¶
type RemoveOptions ¶
type RemoveOptions struct {
// Dirs are explicit target directories to remove from. When provided, agent discovery is
// bypassed and Remove deletes directly from these directories.
Dirs []string
// Global removes from the global install locations rather than project-local ones.
Global bool
// Agents is an optional allowlist of agent types to remove from. When empty and agent
// discovery is enabled, installed agents may be auto-detected.
Agents []AgentType
// Skills is the list of install names to remove. When empty, All must be set.
Skills []string
// All removes all installed skills found in the resolved target directories.
All bool
// Yes is reserved for non-interactive defaults. It is currently unused by Remove.
Yes bool
// EnableAgentDiscovery enables deriving target directories from the canonical skills dir
// and agent-specific skills dirs when Dirs is not provided.
EnableAgentDiscovery bool
}
type RemoveResult ¶
type RemoveResult struct {
Removed []InstalledSkill
}
func Remove ¶
func Remove(opts RemoveOptions) (RemoveResult, error)
Remove deletes installed skills and returns what was removed.
If opts.Dirs is provided, it removes from those directories directly:
- opts.All removes all install names found under the given dirs.
- opts.Skills removes only the specified install names.
Otherwise, agent discovery must be enabled and Remove deletes from the canonical skills directory and per-agent skills directories (filtered by opts.Agents when provided). When removing from global installs, it also updates the skill lock so removed entries no longer participate in update checks.
type SearchResult ¶
type SearchResult struct {
ID string `json:"id"`
SkillID string `json:"skill_id"`
Name string `json:"name"`
Installs int `json:"installs"`
Source string `json:"source"`
}
func SearchSkills ¶
func (*SearchResult) UnmarshalJSON ¶
func (r *SearchResult) UnmarshalJSON(b []byte) error
type Skill ¶
type Skill struct {
Name string
Description string
Compatibility string
AllowedTools []string
Dir string
Content string
Metadata map[string]any
}
func FetchDirectSkillToDir ¶
func ParseSkillMarkdown ¶
type SkillLock ¶
type SkillLock struct {
Skills map[string]LockEntry `json:"skills"`
LastSelectedAgents []AgentType `json:"last_selected_agents,omitempty"`
Dismissed map[string]bool `json:"dismissed,omitempty"`
}
func ReadSkillLock ¶
func (*SkillLock) UnmarshalJSON ¶
type SkillSource ¶
type SkillSource struct {
Type SkillSourceType `json:"type"`
SourceURL string `json:"source_url,omitempty"`
Owner string `json:"owner,omitempty"`
Repo string `json:"repo,omitempty"`
Ref string `json:"ref,omitempty"`
Subpath string `json:"subpath,omitempty"`
SkillFilter string `json:"skill_filter,omitempty"`
ProviderID string `json:"provider_id,omitempty"`
InstallName string `json:"install_name,omitempty"`
WellKnownURL string `json:"well_known_url,omitempty"`
}
func ParseSource ¶
func ParseSource(input string) (SkillSource, error)
func (*SkillSource) UnmarshalJSON ¶
func (s *SkillSource) UnmarshalJSON(b []byte) error
type SkillSourceType ¶
type SkillSourceType string
const ( SkillSourceTypeLocal SkillSourceType = "local" SkillSourceTypeGitHub SkillSourceType = "github" SkillSourceTypeGitLab SkillSourceType = "gitlab" SkillSourceTypeGit SkillSourceType = "git" SkillSourceTypeDirectURL SkillSourceType = "direct-url" SkillSourceTypeWellKnown SkillSourceType = "well-known" SkillSourceTypeSearchHint SkillSourceType = "search-hint" )
type UpdateCheck ¶
func CheckUpdates ¶
func CheckUpdates(ctx context.Context) ([]UpdateCheck, error)
CheckUpdates compares globally installed skills recorded in the skill lock against their remote source state and returns any detected updates.
Currently, this only checks GitHub-based installs that have both a recorded skill folder path and a recorded folder hash.
func Update ¶
func Update(ctx context.Context) ([]UpdateCheck, error)
Update applies updates for skills reported by CheckUpdates and returns the post-update status.
Updates are applied by re-installing the recorded skill path from GitHub into the global target directories, using symlink install mode and non-interactive defaults.
type WellKnownIndex ¶
type WellKnownIndex struct {
Skills []WellKnownSkillEntry `json:"skills"`
}