Skip to main content
A skill is a procedure rather than a role. It is a named set of instructions that runs in the session’s own context, on the session’s model, with the session’s tools. That is the difference from a subagent, which gets a context of its own.

​
Writing one

Put it at .seri/skills/<name>/SKILL.md for this project, or under your profile root for every project.
The directory names the skill, not the filename. Every file in the tree is called SKILL.md, so the filename could never have carried the name.

​
Running one

You run it. Type / and the name. The completion list shows every command, agent and skill with what each one does, so you do not have to remember exact names. The model runs it. Your description is what it reads to decide when a task calls for this procedure.

​
Arguments

Substitution is a single pass, so a word that itself looks like $1 is not re-scanned. argument-hint is the usage line shown in the completion list. A YAML list under arguments: does the same job, rendered as <mode> <prompt>, and argument-hint wins when a file sets both. Neither one binds a name to a position. Substitution is positional either way, so the names buy you a usage line and nothing more.

​
What a skill costs

A skill’s instructions are never in the prompt. Session start pays for the name, the description and the argument hint. The body stays on disk until the skill actually fires, so a directory of twenty skills costs twenty descriptions rather than twenty procedures. disable-model-invocation: true keeps a skill out of the prompt and out of the model’s reach entirely, leaving /name as its only entry point.

​
Keys that are accepted and ignored

allowed-tools, model and context are part of the Cursor format. seri accepts them and warns at startup naming the file, rather than silently honouring them. A skill runs in the parent’s context, on the parent’s model, with the parent’s tools, so a file reading allowed-tools: Read would otherwise leave you believing the skill is restricted when it is not. The format is Cursor’s, so existing SKILL.md files work when you copy them in. seri does not read .cursor/skills/ itself, for the same reason it does not read .cursor/agents/.

​
The one artifact seri writes for you

After hard-won work, the archivist can propose a skill. It is staged, never applied. <id> also accepts all. An approved file carries author: archivist and the reason it was proposed, so you can always tell which of your skills you wrote and which one seri did.

​
A name that is both

If a skill and an agent share a name, /name runs the agent and seri warns at startup. The skill is still reachable through the skill tool. The collision is reported rather than refused, because neither loader can see the other.