Documentation
¶
Index ¶
Constants ¶
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.
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
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
ExpandCommandsWithError behaves like ExpandCommands, but propagates an ExpansionAbort or context cancellation returned by the runner.
func IsHomeSkillPath ¶ added in v1.66.0
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
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
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 ¶
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
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.