How Skills Run
How a skill is triggered, how the triggering message shapes it, and the prompt that drives its execution.
Trigger paths
/skill-name slash command
Prefix any input with /<skill-name>:
/code-reviewer review the diff in this PR
runtime.MatchSkill runs inside exec.Prepare at execution startup (a skill passed by name is resolved in exec.Start instead, and fails the run when excluded or missing). When it hits, agenvoy synthesizes a run_skill tool_call and corresponding tool_result directly into ToolHistories. Since v1.1.0 that tool result carries the whole activation — the BINDING SKILL rules from configs/prompts/assign_skill.md, skill_execution.md, the built-in tool list and the skill body — and no system message is added, so the system prompt stays unchanged and its prefix cache survives. The slash path is strict execution: every step binds. A SKILL.md with no ask_user step never calls ask_user; a bare /<skill-name> runs on the skill's defaults from its first step.
If the user passed args (/code-reviewer review src/parser.go), the user message strips the /<skill-name> prefix and only the args remain. With no args, the user message keeps the literal /<skill-name> so the LLM still sees the activation context.
Natural-language activation
If an agent decides a task needs a skill mid-execution, it calls run_skill directly. This LLM-initiated path is advisory: the tool returns the skill name, its directory and the body as reference material, and the agent takes the parts that fit rather than running every step. The BINDING SKILL wrapper and skill_execution.md apply only to the slash path.
Skill activation is designed as a tool call (lazy load) rather than a startup-time pre-selection — it avoids paying skill-body tokens for tasks that don't need them.
Multi-skill in one conversation
A conversation can activate multiple skills sequentially. Each activation lands as its own run_skill tool result in the conversation, so a later skill follows an earlier one in the tool history; none of them is written into the system prompt.
User message is binding context
skill_execution.md Mandatory Principle #3 (#5 before v1.0.23): the user message that triggered the skill is binding context, not noise. The LLM treats it as user-supplied parameters/hints to weave into the output.
Concretely:
- SKILL.md describes default behavior
- User message overrides or augments default behavior
- A bare slash command means the skill's defaults; when the user's intent conflicts with a step, the step is followed and the conflict is stated in the final output
Example: /readme-generate private MIT — SKILL.md defines the README structure; the user message specifies private mode + MIT license, both of which override defaults.
Skill execution prompt
The execution loop is driven by configs/prompts/skill_execution.md, which carries the rules every skill obeys (output discipline, tool-name mapping, mandatory principles). Since v1.1.1 one of those principles is to plan before the first step: a Skill with three or more steps opens a write_todo checklist built from its steps as they apply to the request.
Tool-name mapping example: external skills written for the Anthropic SDK may reference AskUserQuestion; agenvoy maps these to ask_user automatically through the Tool Mapping table in skill_execution.md. No alias registration in Go is needed.