> For the complete documentation index, see [llms.txt](/docs/llms.txt). Markdown versions of all docs pages are available by appending .md to any docs URL.

# Skills

A **skill** packages a piece of know-how that an agent can pick up: a set of instructions, together with whatever scripts, command-line tools, or reference files those instructions depend on. You attach a skill to an AgentTemplate by specifying where it comes from, and kagent fetches it and places it where the agent can find it.

## About

A skill is a directory whose root holds a `SKILL.md` file. That file carries front matter naming the skill and describing what it is for, followed by the instructions themselves.

The description makes a skill usable. When an agent starts, it reads the front matter of every skill that is attached to it. The agent then offers those skills to the model as tools that the model can call. The model chooses a skill from its description in the same way that it chooses any other tool. A description that states plainly when to use the skill therefore matters more than the length of the instructions behind it.

A skill can be published on its own, or bundled with other skills in a plugin. For what a plugin contains and how to attach one, see [Plugins](https://kagent.dev/docs/kagent/1.x/skills-and-mcp/plugins/).

## Attach skills to an AgentTemplate

Use `spec.skills` to attach a standalone skill. Each entry gives the skill a name and an immutable source to fetch it from.

```yaml
apiVersion: api.kagent.dev/v1alpha3
kind: AgentTemplate
metadata:
  name: incident-responder
  namespace: kagent
spec:
  modelConfig:
    name: default-model-config
  systemPrompt: You help engineers work through production incidents.
  skills:
    - name: incident-triage
      source:
        oci: registry.example.com/skills/incident-triage@sha256:<digest>
```

| Field | Description |
| --- | --- |
| `skills[].name` | The name that the skill is mounted under, and the name that the model sees. |
| `skills[].source` | The location to fetch this one skill from. The source root must contain a `SKILL.md` file. |
| `source.path` | The directory to select inside the artifact, when the content is not at its root. The path must be relative, and it cannot climb out of the artifact with `..` segments. |

One AgentTemplate accepts up to 50 standalone skills. To give an agent the skills that a plugin contains, [use `spec.plugins` instead](https://kagent.dev/docs/kagent/1.x/skills-and-mcp/plugins#attach-a-plugin-to-an-agenttemplate). An AgentTemplate can use both fields at once.

## Every source is immutable

A skill or a plugin changes what an agent does, so kagent only accepts artifact references that cannot shift underneath a running agent. Each source specifies exactly one of three kinds of artifact, and every kind must be pinned in its own way.

- **`oci`** : An image reference pinned to a digest, in the form `<repository>@sha256:<digest>`. A tag alone is rejected, because a tag can be moved to different content later.
- **`git`** : A repository URL together with a full commit identifier. An abbreviated commit, a branch, or a tag is rejected.
- **`bucket.s3`** : An endpoint, bucket, and key, together with the `versionId` of that exact object version. A region is included where the service requires one for request signing.

If a source sets more than one kind, or none of them, the API server rejects the AgentTemplate with the error `exactly one of the fields in [oci git bucket] must be set`.

For an `oci` source, the Agent Substrate worker pulls the image with the registry credentials that it uses for workload images. The worker must therefore be able to reach the registry, and a private registry must accept those credentials. The agent's egress policies do not need to grant access to the registry. Agent Substrate mounts the image in the agent sandbox as a read-only volume, and the agent runtime reads the skill or plugin from that volume.

Each distinct `oci` image uses one mounted volume, and entries that reference the same image share that volume. Agent Substrate allows 32 volumes for each Actor. kagent reserves three of them for runtime data and leaves the other 29 for `oci` images. Because kagent runs an agent and its [subagents](https://kagent.dev/docs/kagent/1.x/examples/agent-delegation#about-subagent-bindings) in one Actor, the limit covers the skills and plugins of every AgentTemplate in the subagent tree. kagent rejects a revision over the limit with the error `runtime revision has <n> volumes and <n> container mounts; Substrate supports at most 32 volumes and 32 mounts per container`.

Publishing a new version means updating the AgentTemplate to reference the new digest, commit, or object version. The update produces a new revision. Agents that are already running keep the content that they started with.

## Naming rules

kagent checks skill names before it fetches anything. These rules apply to every skill on an AgentTemplate, whether the skill is standalone or comes from a plugin.

- A name must be a single path component. A name containing a slash, or a name of `.` or `..`, is rejected.
- Names must be unique across the whole AgentTemplate. Because standalone skills and plugin skills are mounted into the same place, a standalone skill cannot reuse the name of an enabled plugin skill, and two plugins cannot both contribute the same name.