Skills

Package instructions and supporting files as skills, and attach them to an AgentTemplate.

A skillSkillA packaged piece of know-how that an agent can pick up: a directory holding a SKILL.md file of instructions, plus any scripts, command-line tools, or reference files those instructions use. You attach a skill to an AgentTemplate by specifying where it comes from.Learn more 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 AgentTemplateAgentTemplateA Kubernetes custom resource defining what an agent does: its model, system prompt, tools, skills, and plugins. It runs only once an Agent pairs it with a Harness.Learn more 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 pluginPluginA bundle that an AgentTemplate attaches with spec.plugins. A plugin contains skills and can also declare Model Context Protocol servers. Plugins follow the Agent Plugins specification.Learn more. For what a plugin contains and how to attach one, see 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.

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. 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.

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.

About tools Plugins