Skills¶

A skill is a Markdown file that teaches an agent how to do something — a procedure, a policy, a bit of domain knowledge — that the agent reads on demand, only when a task actually calls for it. You author a skill as a SKILL.md file inside your module, give it a short description, and attach it to one or more agents.

Skills are how you give an agent extra know-how without bloating its base instructions. Instead of stuffing every procedure into the agent's prompt, you write each one as its own skill. The agent sees a one-line summary of each attached skill up front and only pulls in the full text when the current task matches.

Skills vs. tools¶

Skills and tools both extend an agent, but they are different things:

	Skill	Tool
What it is	Instructions and knowledge	Executable Python code
Format	A `SKILL.md` Markdown file	A Python function
What the agent does with it	Reads it and acts on the guidance	Calls it and gets a result back
Use it for	Procedures, policies, how-tos, reference material	Fetching data, performing actions, computing results

Tip

Reach for a skill when you want to teach the agent how to think about something or how to carry out a procedure in its own words. Reach for a tool when you need the agent to do something deterministic — read a record, call an API, run a calculation. The two compose well: a skill can describe when and how to use a tool.

Anatomy of a `SKILL.md`¶

A skill is a single Markdown file named SKILL.md. It has two parts:

YAML frontmatter — a fenced block at the very top with exactly two keys, name and description.
A Markdown body — everything after the frontmatter. This is the actual procedure or knowledge the agent reads.

---
name: greeter
description: Greet the user warmly. Use when the user says hello.
---
# Greeter
Say hello back, warmly.

Frontmatter keys¶

Key	Type	Required	Purpose
`name`	string	Yes	The skill's identifier. Must match the name of the folder that contains the `SKILL.md` file.
`description`	string	Yes	A short statement of what the skill does and when to use it. This is what the agent sees before deciding whether to read the body.

Write the description so it answers "when should I open this?" — state the situation, not just the topic. Greet the user warmly. Use when the user says hello. tells the agent both what the skill does and the trigger for using it.

The body¶

Everything below the closing --- is the body. It is plain Markdown and can be as long or as detailed as you need — steps, rules, examples, checklists, edge cases. The agent reads it in full once it decides the skill is relevant.

Where skills live¶

Each skill gets its own folder under a skills/ directory in your module, and the folder name is the skill's name:

skillmod/
├── module.yaml
└── skills/
    └── greeter/
        └── SKILL.md

To make Victor pick up the folder, declare it in your module.yaml with the skills key — usually pointing at the skills directory alongside agents:

name: skillmod
label: Skill Fixture
version: 0.1.0
requires: [base]
agents: [agents]
skills: [skills]

Add one folder per skill under skills/, each holding its own SKILL.md.

The name must match the directory

The frontmatter name must equal the folder name, or the skill is skipped entirely. In this example the folder is mismatch but the frontmatter says not-mismatch, so Victor ignores it:

---
name: not-mismatch
description: Frontmatter name does not match the directory, so this is skipped.
---
# Should be skipped

If a skill you expect isn't showing up, check that skills/<name>/SKILL.md and the frontmatter name agree.

Attaching a skill to an agent¶

A skill does nothing until an agent has it. There are two ways to attach one.

In code¶

On a code-defined agent, list the skill names in a skills class attribute. Each entry is a skill's name (which is also its folder name):

from victor import agents


class Skillhost(agents.Agent):
    name = "skillhost"
    label = "Skillhost"
    model = "anthropic:claude-sonnet-4-6"
    instructions = "You greet users using the greeter skill."
    skills = ["greeter"]

Here the skillhost agent is given the greeter skill. At runtime the agent knows the skill's name and description, and reads the # Greeter body only when a conversation actually calls for a greeting.

In the UI¶

You can also author and attach skills without touching code. Go to Settings → Skills to create a skill record with three fields:

Field	Meaning
`name`	The skill's identifier
`description`	What it does and when to use it
`content`	The Markdown body

Then open the agent's form and add the skill to its Skills field. This is the same skill mechanism as SKILL.md files — just authored through the interface instead of shipped in a module.

Progressive disclosure¶

Skills stay cheap because the agent doesn't read all of them all the time. For every attached skill, the agent is shown only the name and description up front — a compact menu of "here's what I know how to do." It reads the full SKILL.md body only when the current task matches a skill's description.

This means you can attach many skills to an agent without overwhelming it or its context. The cost of an attached-but-unused skill is just its one-line description; the detailed body is loaded lazily, exactly when it's relevant. Write descriptions that make the match obvious, and keep each skill focused on one procedure so the agent can pick the right one.

Checklist¶

[ ] Skill lives at skills/<name>/SKILL.md in your module.
[ ] Frontmatter has both name and description.
[ ] Frontmatter name matches the folder name exactly.
[ ] description says what the skill does and when to use it.
[ ] The module's module.yaml declares skills: [skills].
[ ] Each agent that should use the skill lists it in skills = [...] (or has it added via the agent form).

Agents — attach skills to an agent and configure its model and instructions.
Tools — the executable counterpart to skills, for actions and data.
Modules — how module.yaml wires up your module's directories.