Skills

A skill is a set of instructions written for the agent, teaching it to use the abilities it already has to get a certain kind of task done, such as how to design a house, how to fight the Ender Dragon, or how to tame and look after maids. A skill does not give the agent new abilities; it only teaches the agent to combine the existing Lua APIs and use them well. If you are not sure yet whether to write a skill or a plugin, read the Architecture Overview first.

The skill format follows Agent Skills, so anyone who has written agent skills before will pick it up quickly.

How Skills Are Loaded

A detailed set of instructions is often long. If every skill were stuffed into the system prompt, the model's context would fill up fast. So Numen loads skills on demand, in three levels.

1. Index. In every turn, the model can see the name and one-line description of every skill in the system prompt.
2. Body. When the model decides that the task at hand matches a skill, it calls the skill tool to load that skill's body into the conversation.
3. Supporting files. The body can mention other files by relative path, and the model loads them separately when it needs them.

Take the built-in building_design as an example. Its body only covers the general design process, while more than twenty styles, such as Baroque, classical Chinese and cyberpunk, each live in their own supporting file, and the model reads only the one for the style it is about to build.

Directory Structure

A skill is a folder. It must contain a SKILL.md; every other file is optional.

taming_maid/
├── SKILL.md          Required: the skill's name, description and body
└── references/       Optional: supporting files referenced in the body
    └── maid_types.md

Writing SKILL.md

SKILL.md has two parts: the metadata at the top, wrapped in two --- lines, and the body after it.

---
name: taming_maid
description: Tame a wild Touhou Little Maid. Load when the owner wants a maid or asks you to tame one.
---

# Taming a Maid

Wild maids are tamed with a cake. First make sure there is a cake in the inventory; if not, make one first.

Find a wild maid, walk up to her, and right-click her while holding the cake:

~~~lua
-- List friendly mobs within 16 blocks (maids belong to this group), sorted from nearest to farthest
local mobs = numen.scan.entities("passive", {radius = 16})

-- Check them one by one and find the first maid who has no owner yet
local maid = nil
for _, e in ipairs(mobs) do
  -- type is the entity ID; an empty owner means she is still wild
  if e.type == "touhou_little_maid:maid" and e.owner == nil then
    maid = e
    break
  end
end

-- No wild maid nearby, so stop here
if maid == nil then
  return "No wild maid nearby"
end

-- Walk to within 2 blocks of her
numen.move.to(maid, {arrive = "near", range = 2})

-- Right-click her while holding the cake from the inventory
numen.use.entity(maid, {item = "minecraft:cake"})
~~~

Once tamed, you will receive a `maid_tamed` event. Someone else's maid cannot be tamed with a cake, so don't keep trying.

The metadata has just two fields.

Field	Description
name	The skill's name, which is also the name the model uses to load it. Numen identifies skills by this name, regardless of what the folder is called, but keeping the two the same is recommended.
description	One sentence on what the skill covers and when to use it. A skill without a description does not appear in the index: the model cannot see it, so it will never use it.

The metadata only supports single-line key: value pairs, not multi-line or nested YAML.

Writing a Good Skill

The description decides whether a skill gets used. The model judges whether to load a skill only by its description in the index, so the description should make clear both "what it covers" and "when to use it". For example, the last sentence of the building_design description is "Load BEFORE designing or building any non-trivial structure", which tells the model explicitly to load it before it starts building.

Give plenty of code that can be copied. What models do best is adapt from examples. Rather than describing "scan first, then move" in words, give a commented piece of Lua code directly.

Spell out what to do when things fail. For example, the skill above says "someone else's maid cannot be tamed, so don't keep trying", which saves the model many pointless retries.

Split long reference material into supporting files. The body should only say which file to read in which situation, for example "before building in the Chinese style, read references/chinese_classical.md first". Supporting files must be text, no larger than 256KB each, and their paths cannot point outside the skill folder.

Of course, all of the above is just personal experience and may not apply everywhere. We can let the evaluation do the talking: if your approach scores higher, fine, you win, and I'll go with yours.

Installing Skills

Put the skill folder into config/numen/skills/ under your game directory, then press F3 + T to reload resources or restart the game, and the new skill takes effect. The same goes for editing the body of an existing skill.

Mods can also ship their own skills through plugins. See Plugins.

Override rule. If the player's config/numen/skills/ has a skill with the same name as a mod's skill, the player's version wins. Players can use this to rewrite the skills a mod ships with to suit their own needs.