Documentation
¶
Overview ¶
Package agents provides discovery and parsing of named agent definitions.
Named agents are reusable subagent presets defined in markdown files with YAML frontmatter. The filename (minus the .md extension) becomes the agent name, the frontmatter configures the agent, and the markdown body is used as the agent's system prompt.
Discovery follows Kit's existing skills/prompts conventions:
$XDG_CONFIG_HOME/kit/agents/ user-level agents (default ~/.config/kit/agents/) <project>/.agents/agents/ project-local cross-client agents <project>/.kit/agents/ project-local Kit agents
Project-level agents take precedence over user-level agents, which take precedence over the built-in agents shipped with Kit. An agent with `disabled: true` removes it (and anything it shadows) from the final set.
Index ¶
Constants ¶
const ( SourceBuiltin = "builtin" SourceUser = "user" SourceProject = "project" )
Source values identifying where an agent definition was discovered.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Agent ¶
type Agent struct {
// Name identifies the agent. Derived from the definition filename
// (minus the .md extension) for file-based agents.
Name string
// Description summarises what the agent does. Required — it is
// advertised to the LLM in the subagent tool description.
Description string
// Model optionally overrides the spawning agent's model
// (e.g. "anthropic/claude-sonnet-4"). Empty inherits the parent model.
Model string
// Tools is an optional allowlist of tool names available to the agent.
// Empty means the default subagent tool set (all tools except
// "subagent").
Tools []string
// Temperature optionally overrides the sampling temperature.
Temperature *float32
// Timeout optionally bounds the agent's execution time. Zero uses the
// subagent default.
Timeout time.Duration
// Hidden excludes the agent from the subagent tool description while
// keeping it resolvable by name.
Hidden bool
// Disabled removes the agent from the discovered set entirely.
Disabled bool
// SystemPrompt is the agent's system prompt (the markdown body).
SystemPrompt string
// FilePath is the on-disk path of the definition file. Empty for
// built-in agents.
FilePath string
// Source records where the agent was discovered: "builtin", "user",
// or "project".
Source string
}
Agent is a named, reusable subagent preset.
func Builtins ¶
func Builtins() []*Agent
Builtins returns the built-in agents shipped with Kit. They can be overridden (or disabled) by user- or project-level definitions with the same name.
func Load ¶
Load parses a single agent definition file. The agent name is derived from the filename (minus the .md extension). A missing or empty description in the frontmatter is an error.
func LoadAgents ¶
LoadAgents discovers named agents from the standard locations, applies precedence, and filters out disabled agents. cwd is the working directory for project-local discovery; if empty, the current working directory is used.
Precedence (highest to lowest):
- <cwd>/.agents/agents/ (project, cross-client convention)
- <cwd>/.kit/agents/ (project, Kit-specific)
- $XDG_CONFIG_HOME/kit/agents/ (user, default ~/.config/kit/agents/)
- built-in agents
When two definitions share a name, the higher-precedence one wins. An agent marked `disabled: true` is dropped after precedence resolution, so a project can disable a built-in or user-level agent by shadowing it.
Per-file parse failures do not abort discovery: the aggregated error is returned alongside the successfully loaded agents.
func LoadFromDir ¶
LoadFromDir loads all agent definitions (*.md files) directly inside dir. A missing directory is not an error. Files that fail to parse are skipped; their errors are aggregated into the returned error alongside the successfully parsed agents.
func Merge ¶
Merge combines agent sets ordered from highest to lowest precedence. The first definition of a name wins; later definitions of the same name are dropped. Agents marked Disabled are removed after precedence resolution, so a high-precedence disabled definition also removes anything it shadows.
Source Files