en

# Skill

Agent Skills package reusable workflows as folders with a `SKILL.md`
spec plus optional docs and scripts. During a conversation, the agent
injects a low‑cost “overview” first, then loads the full body/docs only
when actually needed, and runs scripts inside an isolated workspace.

Background references:
- Engineering blog:
  https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
- Open Skills repository (structure to emulate):
  https://github.com/anthropics/skills

## Overview

### 🎯 What You Get

- 🔎 Overview injection (name + description) to guide selection
- 📥 `skill_load` to pull `SKILL.md` body and selected docs on demand
- 📚 `skill_select_docs` to add/replace/clear docs
- 🧾 `skill_list_docs` to list available docs
- 🧪 Execution: `skill_load` materializes a writable skill working copy
  under `/skills/<name>/`, and scripts are executed via `workspace_exec`
  (available whenever a code executor is configured)
- 🗂️ Output file collection via glob patterns with MIME detection
- 🧩 Pluggable local or container workspace executors (local by default)

### Three‑Layer Information Model

1) Initial “overview” (very low cost)
   - Inject only `name` and `description` from `SKILL.md` into the
     system message so the model knows what skills exist.

2) Full body (on demand)
   - When a task truly needs a skill, the model calls `skill_load`. The
     framework then materializes that skill’s full `SKILL.md` body into
     the next model request (see “Prompt Cache” below).

3) Docs/Scripts (selective + isolated execution)
   - Docs are included only when requested (via `skill_load` or
     `skill_select_docs`). Scripts are not inlined; they are executed
     inside a workspace, returning results and output files.

### Caller-Declared Skill Loads

Applications that already know which skill a request requires can load it
without asking the model to choose or call `skill_load`:

```go
events, err := runner.Run(
    ctx,
    userID,
    sessionID,
    model.NewUserMessage("Review this change"),
    agent.WithSkillLoads(skill.LoadRequest{
        Name: "code-review",
        Docs: []string{"references/security.md"},
    }),
)
```

The declarations are validated as one atomic batch against the invocation's
effective repository, including context-aware visibility filters. The
repository selected during preflight and the validated contents of declared
skills are reused for tool construction and request processing throughout that
invocation. `SKILL.md` is always loaded;
`Docs` selects additional skill-relative documents, while `IncludeAllDocs`
selects all supporting documents and cannot be combined with `Docs`. A
non-empty `Docs` replaces the current document selection. When both fields are
unset, the declaration itself leaves any current selection unchanged, matching
`skill_load`. In the default `turn` mode, the turn reset and declaration are
applied atomically; the reset removes the previous turn's selection, so it is
not inherited. Modes without a turn reset, including `session`, preserve a
selection that is still present. Equivalent declarations for the same skill
are coalesced after normalization, including when separate `WithSkillLoads`
options append them. Equivalence requires the same normalized `Docs` set and
`IncludeAllDocs` value. Conflicting selections for one skill are invalid, and
`MaxLoadedSkills` counts the coalesced skills. A failed declaration prevents
the first model request and
can be classified with `skill.ErrInvalidLoadRequest` or
`skill.ErrSkillUnavailable` when the agent returns the setup error directly.
Runner wrappers that execute inner agents asynchronously, such as candidate
selection and Ralph Loop, retain their existing error-event delivery
semantics while still preventing the model request.

Declared loads use the same state, materialization, load-mode, workspace, and
tool-activation behavior as `skill_load`, but do not fabricate a model tool
call or tool result. They apply only to the selected entry invocation and are
not inherited by cloned child-agent invocations. A selected agent that does
not implement `agent.InvocationSkillLoadSupport` (or reports false) is rejected
with `agent.ErrSkillLoadingUnsupported`. Custom agents that implement this
interface commit to consuming the declarations atomically before their first
model request.

### Token Cost

If you inline a full skills repo (all `SKILL.md` bodies and docs) into
the prompt up-front, it can dominate your prompt-token budget and even
exceed the model context window.

For a reproducible, **runtime** token comparison (progressive disclosure
vs full injection), see [trpc-agent-go-benchmark/anthropic_skills/README.md](https://github.com/trpc-group/trpc-agent-go-benchmark/blob/main/anthropic_skills/README.md) and run
the `token-report` suite described there.

### Prompt Cache

Some model providers support **prompt caching**: if a later model request
starts with the exact same tokens as an earlier request, the provider
can reuse that shared **prefix** from cache. This reduces work and can
lower latency and/or input token cost (provider-dependent).

For Skills, *where* the loaded `SKILL.md` body/docs land in the message
sequence affects how long the shared prefix is:

- Legacy behavior (default): loaded skill bodies/docs are appended to the
  **system message**.
  - This inserts new tokens **before** the user message and history,
    which can shorten the shared prefix between consecutive model calls.
- Tool-result materialization (optional): loaded skill bodies/docs are
  appended to the matching **tool result** messages (`skill_load` /
  `skill_select_docs`).
  - This keeps the system message stable, so earlier messages are less
    likely to shift, and prompt caching can often reuse a longer prefix.

Fallback: if the matching tool result message is not present in the
request history (for example, history suppression), the framework can
fall back to a dedicated system