Documentation
¶
Overview ¶
Package agentgen scaffolds Claude Code subagent definitions — the YAML-frontmatter + markdown-body files that live under `~/.claude/agents/<name>.md` (or `./.claude/agents/<name>.md` for project-scoped). Sister of skillgen: same template-renderer pattern, same dual-surface (CLI + MCP) ownership rules.
Why this lives here, not in cli or tools/core: both the `clawtool agent new` CLI and the AgentNew MCP tool need the same templating + validation. Putting Render and IsValidName in a leaf package lets each surface stay an importer rather than re-implementing the renderer.
Terminology distinction (per operator's 2026-04-27 ruling):
- **agent** = a USER-DEFINED PERSONA (this package). A persona has a name, description, allowed-tools list, system-prompt body, and OPTIONALLY a default `instance` it dispatches to via clawtool's SendMessage layer.
- **instance** = a configured running upstream CLI bridge (claude, codex, opencode, gemini, hermes, openclaw, …). Lives in internal/agents/supervisor.go (legacy package name; pre-dates this terminology split). An agent is ASSIGNED an instance; instances are not the agent.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsValidName ¶
IsValidName enforces kebab-case [a-z0-9-]+ with no leading or trailing dash. Same rule skillgen uses; keeps agent file paths portable and prevents hyphen-prefix shell-arg footguns.
func LocalAgentsRoot ¶
func LocalAgentsRoot() string
LocalAgentsRoot is the project-scope analogue: ./.claude/agents.
func ParseTools ¶
ParseTools turns "a, b ,c" into ["a","b","c"] — comma-separated, whitespace-trimmed, empties dropped. Used for both CLI flags and MCP arguments to populate the frontmatter `tools:` list.
func Render ¶
func Render(args RenderArgs) string
Render builds the subagent definition file: YAML frontmatter followed by a body skeleton. Output is byte-identical between the CLI and MCP surfaces because both go through this function.
func UserAgentsRoot ¶
func UserAgentsRoot() string
UserAgentsRoot returns ~/.claude/agents (or $CLAUDE_HOME/agents when set). Never empty — degrades to ".claude/agents" if the home directory can't be resolved.
Types ¶
type RenderArgs ¶
type RenderArgs struct {
Name string
Description string
// Tools is the frontmatter `tools:` list — what Claude Code
// will whitelist for this subagent. Empty = inherit parent
// agent's tool set (Claude Code's default).
Tools []string
// Instance is the optional default clawtool instance this
// agent dispatches to. When set, the body includes a
// "Default instance: <name>" line so the agent and the
// reader both know which upstream gets called.
Instance string
// Model is the optional `model:` frontmatter field
// (sonnet | haiku | opus). Empty = Claude Code default.
Model string
}
RenderArgs bundles every input the renderer needs. We use a struct rather than positional args so adding new fields (e.g. `model`, `instance`) is a non-breaking change for callers.
Source Files