Documentation
¶
Index ¶
- Constants
- Variables
- func AgentIDs() []string
- func AppendGitMetadata(repoPath string, annotations map[string]string)
- func BuildArtifact(srcDir string, skillNames []string) ([]byte, error)
- func CheckSkillConflicts(catalog *fluxcdv1.AgentCatalog, repo string, newSkillNames []string) error
- func CopySkillDir(src, dst string) error
- func DefaultSkillsDir() (string, error)
- func DeriveGitHubOwner(repo string) string
- func DiffArtifact(ctx context.Context, repo string, tag string, localData []byte) error
- func DiscoverSkills(dir string) ([]string, error)
- func FilterSkillNames(discovered []string, targets []string) ([]string, error)
- func HashSkillDir(dir string) (string, error)
- func IsGitHubContainerRegistry(repo string) bool
- func LoadCatalog(dir string) (*fluxcdv1.AgentCatalog, error)
- func NormalizeGitURL(url string) string
- func NormalizeRepository(repo string) string
- func ParseAnnotations(args []string) (map[string]string, error)
- func ProjectRoot() (string, error)
- func PushArtifact(ctx context.Context, repo string, data []byte, opts PushArtifactOptions) (string, error)
- func RemoveAgentSymlinks(projectRoot string, agents []string, skillNames []string) error
- func RemoveEmptyDir(dir string)
- func ResolveDigest(ctx context.Context, ociURL string) (string, error)
- func SaveCatalog(dir string, catalog *fluxcdv1.AgentCatalog) error
- func SaveCatalogLock(dir string, catalog *fluxcdv1.AgentCatalog) error
- func SyncAgentSymlinks(projectRoot string, agents []string, skillNames []string) error
- func SyncSkills(skillsDir, srcDir string, oldChecksums map[string]string, skillNames []string, ...) ([]string, []fluxcdv1.AgentCatalogSkill, error)
- func UsesDefaultSkillsDir(info *AgentInfo) bool
- func ValidateSkillName(name string) error
- type AgentInfo
- type ArtifactInfo
- type PushArtifactOptions
- type SkillDrift
Constants ¶
const ( // DefaultSkillsDirName is the directory name for skills relative to .agents/. DefaultSkillsDirName = ".agents/skills" // DefaultGlobalSkillsDirName is the global skills directory path. DefaultGlobalSkillsDirName = "~/.config/agents/skills" // CatalogFileName is the name of the catalog spec file. CatalogFileName = "catalog.yaml" // CatalogLockFileName is the name of the catalog lock file. CatalogLockFileName = "catalog-lock.yaml" )
const ( // AnnotationCreated is the OCI annotation key for the image creation timestamp. AnnotationCreated = "org.opencontainers.image.created" // AnnotationSource is the OCI annotation key for the source repository URL. AnnotationSource = "org.opencontainers.image.source" // AnnotationRevision is the OCI annotation key for the source revision. AnnotationRevision = "org.opencontainers.image.revision" // AnnotationVersion is the OCI annotation key for the image version. AnnotationVersion = "org.opencontainers.image.version" )
const (
// SkillFileName is the name of the skill metadata file.
SkillFileName = "SKILL.md"
)
Variables ¶
var ErrDiffIdentical = errors.New("artifact contents are identical")
ErrDiffIdentical is returned by DiffArtifact when the local and remote content layers are identical.
Functions ¶
func AppendGitMetadata ¶
AppendGitMetadata auto-populates OCI annotations from git metadata. It only sets annotations that are not already present in the map. Errors are silently ignored (git not installed, not a repo, etc.).
func BuildArtifact ¶
BuildArtifact creates a tar+gzip archive containing only the specified skill directories from srcDir. It strips environment metadata (uid, gid, timestamps) for reproducibility, and skips symlinks and non-regular files.
func CheckSkillConflicts ¶
func CheckSkillConflicts(catalog *fluxcdv1.AgentCatalog, repo string, newSkillNames []string) error
CheckSkillConflicts checks if any skill name in newSkillNames is already installed by a different source in the catalog.
func CopySkillDir ¶
CopySkillDir performs a safe recursive directory copy. It skips symlinks and non-regular files to prevent symlink-based path traversal.
func DefaultSkillsDir ¶
DefaultSkillsDir resolves the skills directory to an absolute path relative to the current working directory. If the path exists, it verifies that it is a real directory (not a symlink).
func DeriveGitHubOwner ¶
DeriveGitHubOwner extracts the GitHub owner from a ghcr.io repository URL.
func DiffArtifact ¶
DiffArtifact compares the local artifact data against the content layer of the remote artifact at the given tag. It fetches only the remote manifest and compares the Flux content layer digest. It returns ErrDiffIdentical if the content is the same, nil if different. Failures are treated as "different" (fail open).
func DiscoverSkills ¶
DiscoverSkills walks top-level subdirectories of dir, finding those with a valid SKILL.md file. Returns the list of skill names.
func FilterSkillNames ¶
FilterSkillNames returns only the skill names present in the target list. If targets is empty, all discovered names are returned unchanged. Returns an error if any target name is not found in the discovered set.
func HashSkillDir ¶
HashSkillDir computes the SHA-256 directory hash of a skill directory.
func IsGitHubContainerRegistry ¶
IsGitHubContainerRegistry checks if the repository host is ghcr.io.
func LoadCatalog ¶
func LoadCatalog(dir string) (*fluxcdv1.AgentCatalog, error)
LoadCatalog builds a catalog by reading the spec from catalog.yaml and the status from catalog-lock.yaml. The spec in catalog.yaml is authoritative; the spec stored in the lock file is ignored.
func NormalizeGitURL ¶
NormalizeGitURL converts git URLs to HTTPS format. It handles git://, git@host:path SSH URLs, and strips .git suffixes.
func NormalizeRepository ¶
NormalizeRepository strips the oci:// prefix and trailing slashes from a repository URL.
func ParseAnnotations ¶
ParseAnnotations parses a list of key=value strings into a map. It splits on the first '=' only, allowing values to contain '='.
func ProjectRoot ¶
ProjectRoot returns the current working directory, which is the root of the project where skills and agent symlinks are managed.
func PushArtifact ¶
func PushArtifact(ctx context.Context, repo string, data []byte, opts PushArtifactOptions) (string, error)
PushArtifact creates a Flux OCI artifact from the pre-built data and pushes it to the specified repository. It returns the artifact digest.
func RemoveAgentSymlinks ¶
RemoveAgentSymlinks removes per-skill symlinks for each agent and cleans up empty agent skill directories and their parents.
func RemoveEmptyDir ¶
func RemoveEmptyDir(dir string)
RemoveEmptyDir removes a directory if it is empty. Errors are silently ignored.
func ResolveDigest ¶
ResolveDigest resolves the digest of an OCI artifact without downloading it.
func SaveCatalog ¶
func SaveCatalog(dir string, catalog *fluxcdv1.AgentCatalog) error
SaveCatalog atomically writes the catalog spec to catalog.yaml in the given directory.
func SaveCatalogLock ¶
func SaveCatalogLock(dir string, catalog *fluxcdv1.AgentCatalog) error
SaveCatalogLock atomically writes the full catalog to catalog-lock.yaml in the given directory.
func SyncAgentSymlinks ¶
SyncAgentSymlinks creates per-skill symlinks for each agent that uses a custom skills directory. TargetAgents using the default skills directory are silently skipped. The symlinks are relative so they remain valid across machines. Existing correct symlinks are left in place; wrong targets are replaced. Returns an error if a target path exists as a non-symlink.
func SyncSkills ¶
func SyncSkills(skillsDir, srcDir string, oldChecksums map[string]string, skillNames []string, restoring bool) ([]string, []fluxcdv1.AgentCatalogSkill, error)
SyncSkills computes checksums from a source directory, compares them against old checksums (from inventory) or installed checksums (when restoring), removes orphaned skills, and copies only changed skills to the install directory. Returns the list of changed skill names and the full skill metadata.
func UsesDefaultSkillsDir ¶
UsesDefaultSkillsDir returns true if the agent's project path is the default skills directory (no symlink needed).
func ValidateSkillName ¶
ValidateSkillName validates a skill name per the Agent Skills specification.
Types ¶
type AgentInfo ¶
type AgentInfo struct {
// Name is the human-readable agent name.
Name string
// ID is the unique identifier used with the --agent flag.
ID string
// ProjectPath is the skills directory path relative to the project root.
ProjectPath string
// GlobalPath is the global skills directory path (~ is expanded at runtime).
GlobalPath string
}
AgentInfo holds the configuration for an AI agent's skills directory.
type ArtifactInfo ¶
type ArtifactInfo struct {
// Digest is the artifact digest string (e.g. "sha256:...").
Digest string
// Annotations holds the manifest annotations.
Annotations map[string]string
}
ArtifactInfo holds metadata from a pulled OCI artifact.
func PullArtifact ¶
func PullArtifact(ctx context.Context, ociURL, dstDir string) (*ArtifactInfo, error)
PullArtifact pulls a Flux OCI artifact, finds the content layer by media type, and extracts it to dstDir. It returns the artifact metadata.
type PushArtifactOptions ¶
type PushArtifactOptions struct {
// Tags is the list of tags to apply to the artifact.
Tags []string
// Annotations is the map of OCI manifest annotations.
Annotations map[string]string
}
PushArtifactOptions holds configuration for pushing an OCI artifact.
type SkillDrift ¶
type SkillDrift struct {
// Name is the skill name.
Name string
// Reason is a human-readable description of the drift (e.g. "deleted", "modified").
Reason string
}
SkillDrift describes a skill that has drifted from its expected state.
func CheckSkillIntegrity ¶
func CheckSkillIntegrity(skillsDir string, skills []fluxcdv1.AgentCatalogSkill) []SkillDrift
CheckSkillIntegrity verifies that each installed skill directory exists and matches its stored checksum. Returns a list of drifted skills, or nil if all intact.
func (SkillDrift) String ¶
func (d SkillDrift) String() string
String returns a formatted drift description.
Source Files