skill

Documentation

Overview

Package skill keeps a copy of each skill folder that a coding session used, and turns the copy into the materials that the evidence holds.

The copy is made when the session uses the skill, not when the session is pushed, so the evidence holds the skill that ran also when its files change before the push. A copy is never replaced: a later use that finds different content only marks the copy as changed.

A copy holds the files of the folder as they are. Secrets are removed only when a package is made from the copy, by the same redaction as the other spec sources.

Index

• Constants
• Variables
• func BaseDir(text string) (string, bool)
• func ContentDigest(src string) (string, error)
• func HasBaseDir(text []byte) bool
• func MarkChanged(dst string) error
• func ParseDir(s string) (string, bool)
• func Source(name, dir string, roots Roots) string
• func Within(path, root string) bool
• type Info
  • func Copy(src, dst string) (Info, error)
  • func Load(dst string) (Info, error)
• type Package
  • func MakePackage(dst string, redact Redactor) (Package, error)
• type Redactor
• type Roots

Constants

const (
	// DefinitionFile is the file that defines a skill. A folder without it is
	// not a skill, and is never read.
	DefinitionFile = "SKILL.md"

	// MaxPackageSize is the largest archive that is uploaded. A larger skill
	// keeps its definition and its counts, and loses its package only.
	MaxPackageSize = 5 << 20
)

Variables

var ErrNotSkill = errors.New("the folder holds no " + DefinitionFile)

ErrNotSkill is returned for a folder that holds no SKILL.md file.

Functions

func BaseDir

func BaseDir(text string) (string, bool)

BaseDir returns the skill folder that a "Base directory for this skill:" line in text names. Claude Code writes a path, and OpenCode a file URL. Only an absolute path is accepted.

func ContentDigest

func ContentDigest(src string) (string, error)

ContentDigest returns the digest of the content of a skill folder, as Copy computes it, without copying anything.

func HasBaseDir

func HasBaseDir(text []byte) bool

HasBaseDir reports whether text can hold a base directory line. It is a cheap test that a scan of a large transcript runs before it decodes a line.

func MarkChanged

func MarkChanged(dst string) error

MarkChanged records that a later use found content in the folder that is not the content of the copy.

func ParseDir

func ParseDir(s string) (string, bool)

ParseDir reads a skill folder as an agent gives it: a path or a file URL. Only an absolute path is accepted.

func Source

func Source(name, dir string, roots Roots) string

Source returns where a skill came from, as one of the aicodingsession.SkillSource* constants. A plugin skill has a name with a plugin prefix (plugin:skill) or a folder in a plugin folder. Otherwise the first root list that holds the folder gives the source, in the order of the Roots fields. A folder that no root holds, or no folder, gives unknown.

func Within

func Within(path, root string) bool

Within reports whether path is root or a path below it.

Types

type Info

type Info struct {
	// Digest identifies the content of the folder when it was copied. The
	// same content gives the same digest in every session.
	Digest string `json:"digest"`
	// Truncated reports a folder over the copy bound. Only its definition was
	// copied, and it gets no package.
	Truncated bool `json:"truncated,omitempty"`
	// SkippedLinks counts the links that point out of the folder, or to a
	// folder, and so were left out.
	SkippedLinks int `json:"skipped_links,omitempty"`
	// Changed reports that a later use found different content in the folder.
	// The copy keeps the content of the first use.
	Changed bool `json:"-"`
}

Info describes a copy.

func Copy

func Copy(src, dst string) (Info, error)

Copy copies the skill folder src into dst, which must not exist yet, and returns what it copied. When another hook renamed its copy into dst first, Copy returns that copy unchanged.

func Load

func Load(dst string) (Info, error)

Load returns the description of an existing copy.

type Package

type Package struct {
	// Definition is the redacted SKILL.md file.
	Definition []byte
	// Archive is a reproducible gzip-compressed tar archive of the redacted
	// folder, or nil when it is over MaxPackageSize or the copy was
	// truncated.
	Archive []byte
	// Oversize reports that the archive was left out for its size.
	Oversize bool
}

Package is what the evidence holds for one skill.

func MakePackage

func MakePackage(dst string, redact Redactor) (Package, error)

MakePackage returns the package of a copy. The first call redacts each text file and keeps the result in the copy, so a later push of the session does not redact an unchanged skill again. Binary files are stored as they are.

Redaction fails closed: a file that could not be scanned fails the package, and nothing of the skill is uploaded.

type Redactor

type Redactor func(doc []byte) ([]byte, error)

Redactor removes secrets from the text of one file.

type Roots

type Roots struct {
	// Plugin holds the folders where the agent installs plugins.
	Plugin []string
	// Organization holds the folders of the managed configuration, which an
	// administrator installs for all users.
	Organization []string
	// User holds the skill folders of the user's agent configuration.
	User []string
	// Project holds the repository and the session folder.
	Project []string
}

Roots are the folders that tell where a skill came from. Each agent has its own layout, so each provider gives its own.