How skills work

What a skill is

ivralo keeps three things apart. The agents are thin: each is built from a preset, which is a key, a set of grants and one hint sentence, with no prompt of its own. The capability is a Python library the agents call into. The expertise, meaning how to read an incident, how to build a workbook or how to fix a failing test, lives in skills.

A skill is a directory with a SKILL.md in it, and optionally scripts and reference notes:

my-skill/
  SKILL.md          frontmatter (name, description) and the body
  scripts/*.py      scripts the agent runs through run_skill_script
  references/*.md   longer notes, read only when needed

Only a directory that holds a SKILL.md counts. The format of the file is on Writing a skill.

How an agent uses one

An agent does not read every skill up front. It sees an index: each skill's name and its description. When a task matches a description, the agent opens that skill's body, and a reference file only if the body points to one. So the description is the part that decides whether a skill is ever used.

Every agent can read a skill's instructions and its references. None can run a skill's script directly: a script runs only through run_skill_script, inside the Python worker, under the same guard as any other Python the agent runs.

The two shelves

Skills sit on two shelves, served as one:

IVRALO_SKILLS_DIR and IVRALO_SKILLS_LOCAL_DIR move either shelf. The two shelves are one namespace: when a local skill has the same name as a shipped one, the shipped copy wins, and ivralo skills and ivralo doctor report the local copy as shadowed. It never loads.

ivralo skills

lists both shelves and whether each skill validates.

Every specialist sees the whole shelf

Owning a skill does not decide who may load it. Every specialist is built with the whole shelf: its own skills listed first with their full description, every other skill by its first sentence. A skill you install is usable by every agent the moment the team is next built.

What ownership decides is what a specialist is for:

• where /skill <name> <request> in a session sends the work;
• what ivralo agents lists under each specialist's own skills;
• which specialist a request that is the skill's whole job goes to.

The team binds skills when it is built, so a running session picks up a change on the next build: /new, a restart, or the rebuild that follows /skill install.

Ownership

A skill's owner is always a preset's key: analyst, coder, investigator and so on. There are two ways to own one.

• A shipped skill is owned through the preset's skills= list in the roster. xlsx belongs to analyst and spreadsheet, incident to investigator. The full list is on Shipped skills.
• A local skill is owned through skills.local/assignments.json, written by ivralo skills assign or by --agent on install and create. Any name that is not a preset's key is refused before anything is written, and the refusal lists every preset.

not a preset: analist - a skill's owner is a preset's key; presets: analyst, spreadsheet, ...

The main agent owns no skills. It sees the whole shelf like everyone else.

A local skill nobody claims

A local skill that no preset owns is not left unused. It joins the team as a specialist of its own, a preset made from the skill:

• its key is the skill's name;
• its hint is the first sentence of the description, plus its "Do NOT load" sentence when it has one;
• it owns the skill;
• its grants are the baseline plus whatever the skill asks for under metadata.ivralo.capabilities.

A skill can ask for more than the baseline in its frontmatter:

metadata:
  ivralo:
    capabilities: [network.web, shell.full]

That request is only honoured for the skill's own specialist, and only when each grant's own conditions hold, the same gates as any preset. When another specialist loads the skill, it runs on that specialist's grants, never on the skill's request. ivralo skills assign <name> --agent <key> folds the skill into an existing preset instead. The grant names and what each one waits for are on Capabilities.

A local skill that fails validation stays off every shelf it was not assigned to, so one broken skill does not stop the team from being built. ivralo doctor says what is wrong with it.

Your framework is your skill

ivralo ships no skill for an application framework or a layer of one: nothing for a web framework, a UI library or an ORM. A test fails the build if a shipped skill names one. The shipped skills teach the method (read the code, reproduce the failure, change one thing, run the project's own checks), and the project's own commands come from its IVRALO.md.

When your team has conventions for its framework, write them as a skill of your own and install it on the local shelf. That keeps the knowledge yours, versioned where you want it, and close to the code it describes.

In a session

Installing, updating and removing are on Installing skills.