skills

package
v1.130.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 1, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source
const KitDirEnv = "DOCKER_AGENT_KIT_DIR"

KitDirEnv names the environment variable that points at a docker-agent kit directory staged by the host before launching a sandbox. When set, local skill discovery is rooted exclusively at the kit's skills directory; the usual $HOME / git-walking lookups are skipped because they target paths that don't exist inside the sandbox.

View Source
const KitSkillsSubdir = "skills"

KitSkillsSubdir is the path inside a kit that holds the staged skills.

Variables

This section is empty.

Functions

func ExpandCommands added in v1.32.5

func ExpandCommands(ctx context.Context, content string, run Runner) string

ExpandCommands replaces all !`command` patterns in content. Runner errors are embedded in the result; callers that need abort semantics should use ExpandCommandsWithError.

func ExpandCommandsWithError added in v1.130.0

func ExpandCommandsWithError(ctx context.Context, content string, run Runner) (string, error)

ExpandCommandsWithError behaves like ExpandCommands, but propagates an ExpansionAbort or context cancellation returned by the runner.

func IsHomeSkillPath added in v1.66.0

func IsHomeSkillPath(path string) bool

IsHomeSkillPath reports whether path is under one of the global skill directories in the user's home directory.

Types

type ExpansionAbort added in v1.130.0

type ExpansionAbort interface {
	error
	AbortExpansion()
}

ExpansionAbort marks an error that must stop command expansion rather than being embedded in the skill content.

type Runner added in v1.130.0

type Runner func(ctx context.Context, command string) (string, error)

Runner executes one command embedded in skill content and returns its stdout. A skill body is untrusted data, so implementations are expected to get the user's consent before running anything on their machine: returning an error keeps the command from running and inlines the reason in the expanded content.

func ShellRunner added in v1.130.0

func ShellRunner(workDir string) Runner

ShellRunner returns a Runner that executes commands with the system shell in workDir. It performs no approval of its own — wrap it to gate execution.

type Skill

type Skill struct {
	Name          string
	Description   string
	FilePath      string
	BaseDir       string
	Files         []string
	Local         bool // true for filesystem-loaded skills, false for remote
	License       string
	Compatibility string
	Metadata      map[string]string
	AllowedTools  []string
	// Toolsets lists names of reusable toolset definitions (from the top-level
	// `toolsets` section) to expose to the skill while it runs as a fork
	// sub-agent (context: fork), in addition to the parent agent's tools.
	// Populated from inline config or the SKILL.md `toolsets` frontmatter.
	// Ignored for non-fork skills.
	Toolsets []string
	Context  string // "fork" to run the skill as an isolated sub-agent
	// Model is an optional model override applied while the skill runs as
	// a sub-agent (context: fork). It accepts either a named model from the
	// agent config or an inline "provider/model" reference (e.g.
	// "openai/gpt-4o-mini"). It is ignored for non-fork skills.
	Model string
	// InlineContent holds the skill body for skills defined directly in the
	// agent config rather than loaded from a file or URL. When set, the
	// skill has no FilePath/BaseDir and its content is served from memory.
	InlineContent string
}

Skill represents a loaded skill with its metadata and content location.

func Load

func Load(ctx context.Context, sources []string) []Skill

Load discovers and loads skills from the given sources. Each source is either "local" (for filesystem-based skills) or an HTTP/HTTPS URL (for remote skills per the well-known skills discovery spec).

Local skills are loaded from (in order, later overrides earlier):

Global locations (under $HOME):

  • ~/.codex/skills/ (recursive)
  • ~/.claude/skills/ (flat)
  • ~/.agents/skills/ (recursive)

Project locations (under cwd, closest wins):

  • .claude/skills/ (flat, only at cwd)
  • .github/skills/ (flat, scanned from each ancestor up to $HOME — or the enclosing git root outside $HOME — down to cwd)
  • .agents/skills/ (flat, same ancestor scan; overrides .github/skills at the same level)

The returned slice is sorted by skill name for deterministic ordering.

func (Skill) ExpandsCommands added in v1.130.0

func (s Skill) ExpandsCommands() bool

ExpandsCommands reports whether !`command` patterns in the skill body may be executed. Local files and the agent config are part of what the user chose to run, and the config already dictates instructions, toolsets and permissions, so a command embedded in it grants nothing it could not already do. A remote body is data fetched from a third-party server at runtime and never earns that authority.

func (Skill) IsFork added in v1.32.5

func (s Skill) IsFork() bool

IsFork returns true when the skill should be executed in an isolated sub-agent context rather than inline in the current conversation. This matches Claude Code's `context: fork` frontmatter syntax.

func (Skill) IsInline added in v1.70.2

func (s Skill) IsInline() bool

IsInline reports whether the skill is defined inline in the agent config (its body lives in InlineContent rather than on disk or behind a URL).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL