Documentation
¶
Overview ¶
Package skills discovers agent skills in git repositories the way the portal backend's /agent-skills endpoint does: every SKILL.md in a GitHub repository is one skill, its frontmatter name and description describe it, and its directory is the skill an agent mounts (url + path). kagent API v2 pins skills to immutable sources, so the ref that was read is resolved to its head commit and reported next to it: the skills entry a listing yields feeds create_agent as is. Results are cached per repository for a short time so a meta agent listing skills repeatedly does not exhaust GitHub's rate limit. The Resolver (resolve.go) is the same GitHub path for the composer: a branch or tag to its head commit, a repository to its default branch.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // CommitPattern is a full commit id (40 or 64 hex characters). CommitPattern = regexp.MustCompile(`^([0-9a-fA-F]{40}|[0-9a-fA-F]{64})$`) // DigestRefPattern is <repository>@sha256:<digest>. DigestRefPattern = regexp.MustCompile(`^[^\s@]+@sha256:[0-9a-f]{64}$`) )
Immutable skill sources as the kagent.dev/v1alpha3 AgentTemplate requires them: a full git commit id, an OCI reference by digest.
var ErrUnresolvable = errors.New("unresolvable skill reference")
ErrUnresolvable marks a reference that could not be resolved to a pin; the message names the repository or image and the reason.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Repositories are the configured skill repositories (github.com URLs).
Repositories []string
// APIURL is the GitHub API base (https://api.github.com; tests override).
APIURL string
// Token authenticates GitHub requests (private repositories, higher rate
// limit); empty is anonymous.
Token string
// CacheTTL keeps a repository's result before it is re-read.
CacheTTL time.Duration
// HTTPClient overrides the client (tests).
HTTPClient *http.Client
}
Config tunes the discoverer and the resolver.
type Discoverer ¶
type Discoverer struct {
// contains filtered or unexported fields
}
Discoverer reads skills from GitHub with a per-repository cache.
func (*Discoverer) List ¶
func (d *Discoverer) List(ctx context.Context, repository, ref string, refresh bool) (*Result, error)
List discovers skills. repository narrows to one repository (configured or not — any github.com URL is accepted); ref overrides the default branch; refresh bypasses the cache.
func (*Discoverer) Repositories ¶
func (d *Discoverer) Repositories() []string
Repositories returns the configured repositories.
type Repository ¶
type Repository struct {
RepoURL string `json:"repoUrl"`
Ref string `json:"ref,omitempty"`
// Commit is what Ref resolved to when the repository was read.
Commit string `json:"commit,omitempty"`
Skills []Skill `json:"skills"`
// Truncated is true when GitHub capped the tree or a SKILL.md read failed:
// some skills may be missing.
Truncated bool `json:"truncated"`
// Error is set when the repository could not be read at all.
Error string `json:"error,omitempty"`
FetchedAt *time.Time `json:"fetchedAt,omitempty"`
}
Repository is the discovery result of one configured repository.
type Resolver ¶ added in v1.0.0
type Resolver struct {
// contains filtered or unexported fields
}
Resolver pins skill references: a git branch or tag to its head commit, a repository to its default branch, an OCI tag to its digest. It is the composer's path to immutable sources and the migration's.
func NewResolver ¶ added in v1.0.0
NewResolver builds a resolver for the GitHub API at apiURL (with token, empty for anonymous) and any OCI registry. registry may be nil.
func (*Resolver) GitHead ¶ added in v1.0.0
GitHead resolves ref (a branch, tag or commit; empty for the default branch) of repoURL to the commit it points at. A ref that is already a full commit id is returned as it is without a lookup. A repository that cannot be read — private without a token, or missing — is ErrUnresolvable naming it.
type Result ¶
type Result struct {
Repositories []Repository `json:"repositories"`
// Skills flattens every repository's skills (stable order).
Skills []Skill `json:"skills"`
}
Result is what list_skills returns.
type Skill ¶
type Skill struct {
// Name is the frontmatter name, else the directory (or repository) name.
Name string `json:"name"`
// Description is the frontmatter description ("" when absent).
Description string `json:"description"`
// RepoURL is the canonical https://github.com/<owner>/<repo>.
RepoURL string `json:"repoUrl"`
// Path is the skill directory; "" at the repository root.
Path string `json:"path"`
// Ref is the git ref (branch) the skill was read from.
Ref string `json:"ref"`
// Commit is the commit Ref resolved to when it was read: the immutable
// reference an agent pins the skill to.
Commit string `json:"commit"`
}
Skill is one discovered skill, shaped as the portal returns it.
Source Files