skill

type MalformedSkillError ¶

type MalformedSkillError struct {
	Name   string // the skill identifier, if known ("" when unknown)
	Reason string // non-secret, human-readable reason for the rejection
}

MalformedSkillError is returned when a SKILL.md document cannot be parsed: it is oversize, has no opening frontmatter fence, has an unterminated fence, or carries a duplicate frontmatter key. The parser is fail-secure and never returns a partial or ambiguous parse alongside this error. It is errors.As-recoverable so the caller can surface the offending skill and a non-secret reason. Name is the skill identifier when known (empty when the raw bytes are parsed before a name is established).

func (e *MalformedSkillError) Error() string

type Skill ¶

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

Skill loads a single named SKILL.md body for the ONE agent it is bound to. It depends only on the narrow SkillLoader (DIP) and its own immutable agent identity; it never imports a product package and holds no allow-map of its own.

workspaceRoot is the OPTIONAL untrusted workspace source. When empty (the default), the tool is embedded-only and behaves exactly as in P2 (auto-approve, no Prepare/gate). When set (via WithWorkspaceRoot at the composition root, for an agent the operator grants runtime skills in Phase 3c), a non-embedded name is resolved as a human-gated workspace load. It is immutable after construction.

func NewSkill(loader SkillLoader, agent identity.AgentName, opts ...SkillOption) *Skill

func (s *Skill) AuditSummary(argsJSON string) string

func (s *Skill) Info(context.Context) (*tool.ToolInfo, error)

func (s *Skill) InvokableRun(ctx context.Context, _ string) (*tool.ToolResult, error)

func (s *Skill) PrepareCall(_ context.Context, executionID uuid.UUID, argsJSON string) (tool.Request, tool.PreparedArtifact, error)

type SkillContainmentError ¶

type SkillContainmentError struct {
	Name   string // the rejected workspace skill name
	Reason string // non-secret, human-readable reason for the rejection
}

SkillContainmentError is returned when an UNTRUSTED workspace skill name or path is rejected by the containment rules of the workspace loader (design §7a): a name that is not a bounded ASCII slug (empty, ".", "..", a path separator, a control character, uppercase, or over-length), or a resolved path that escapes the workspace root (an intermediate-dir or final-file symlink leaving the root, a ".." traversal) or whose target is not a regular file (a directory, device, FIFO, or symlink). It is fail-secure — the load is denied, never guessed — and errors.As-recoverable so the caller can surface the offending name and a non-secret reason WITHOUT loading the untrusted body. It is distinct from UnknownSkillError (an unauthorized embedded name) and SkillNotFoundError (an authorized name whose file is absent): this one means the request itself violated containment.

func (e *SkillContainmentError) Error() string

type SkillDescriber ¶

type SkillDescriber interface {
	Describe(ctx context.Context, agent identity.AgentName, name string) (SkillMeta, error)
}

SkillDescriber resolves a named skill into its frontmatter METADATA (name+description) WITHOUT the body — the data the swarm renders into an agent's <available_skills> catalog. It authorizes (agent, name) against the SAME closed allow-set as SkillLoader.Load, so a catalog can only ever list a skill the agent is actually allowed to load. It is a separate, focused interface (interface segregation): the Skill tool depends only on SkillLoader; the catalog builder depends only on SkillDescriber.

type SkillLoader ¶

type SkillLoader interface {
	Load(ctx context.Context, agent identity.AgentName, name string) (string, error)
	Allowed(agent identity.AgentName, name string) bool
}

SkillLoader resolves a named skill into the markdown body to inject into an agent's context. It is the narrow seam between the Skill tool and the on-disk (embedded) skill catalogue: the tool asks for a body by (agent, name) and the loader is responsible for authorizing the request and reading the document.

The agent identity is a parameter — not loader state — so a single loader can serve every agent in a swarm while still scoping each call to that agent's own allowed-skill set. Implementations MUST be fail-secure: an unauthorized or unknown name is denied, never guessed.

Allowed is the read-only membership predicate over the SAME closed allow-set Load authorizes against, WITHOUT touching the filesystem: it answers "is name an embedded skill this agent may load?". The workspace-aware Skill tool uses it as the embedded-wins discriminator (embedded names auto-approve and resolve via Load; only a NON-embedded name is ever considered for an untrusted workspace load). It is fail-secure: an unknown agent, a nil allow-map, or a non-member name all report false. Both methods are used by the single Skill-tool consumer, so combining them does not over-widen the interface (interface segregation).

type SkillMeta ¶

type SkillMeta struct {
	Name        string
	Description string
}

SkillMeta is the flat, typed view of a SKILL.md frontmatter block. Only the fields the loader needs are surfaced; every other frontmatter key is parsed (to detect duplicates / malformed lines) but otherwise ignored. The frontmatter is treated as inert data — values are trimmed but never executed, interpolated, or otherwise interpreted.

func DiscoverWorkspaceSkills(root string) []SkillMeta

type SkillNotFoundError ¶

type SkillNotFoundError struct {
	Name string // the authorized skill whose SKILL.md is missing
	Err  error  // the wrapped fs error (e.g. fs.ErrNotExist)
}

SkillNotFoundError is returned when a skill name has passed the per-agent authorization check (it is a member of the agent's closed allow-set) but its SKILL.md document is absent from the backing file system. This is distinct from UnknownSkillError — which denies an untrusted, unauthorized name — and signals a catalogue/embed integrity problem (an allowed skill whose file was not shipped) rather than a denied request. It is errors.As-recoverable so the caller can surface the missing skill name; the underlying fs error is wrapped and reachable via errors.Unwrap for diagnostics.

func (e *SkillNotFoundError) Error() string

func (e *SkillNotFoundError) Unwrap() error

type SkillOption ¶

type SkillOption func(*Skill)

SkillOption configures an optional capability on a Skill at construction. Options are applied at the composition root only; the resulting Skill is immutable.

func WithWorkspaceRoot(root string) SkillOption

type UnknownSkillError ¶

type UnknownSkillError struct {
	Agent identity.AgentName // the agent that requested the skill
	Name  string             // the requested (unknown/unauthorized) skill name
}

UnknownSkillError is returned when a skill is requested by name that is not known to — or not authorized for — the requesting agent. It is fail-secure: the Skill tool denies the invocation rather than guessing. It is errors.As-recoverable so the caller can report which agent asked for which skill without leaking the (curated) skill catalogue.

func (e *UnknownSkillError) Error() string