Skills and instructions

Standing instructions are a short note that every session receives on every turn. Skills are longer, task-specific guidance that an agent picks up only when the task calls for it. Both are ordinary documents, so you write and edit them like any other.

How it works

Standing instructions work like an AGENTS.md. The World has one set, read by every session in every project. A project can have its own as well, read by its sessions after the World's. Keep them to the few things that are always true there, such as how to write and what to check before saying something works, because every session pays for them on every turn.

A skill is a catalog entry over an ordinary document. The entry has a title and a one-line description of the task it is for, and it points at a SKILL.md document holding the instructions. The catalog reaches every turn, one line per skill. The agent chooses on that line alone and reads the full text only when it matches the task, so a World can carry fifty skills at the cost of fifty lines.

A skill registered in the World is served in every project, on every device, to every harness. A skill registered in a project is served only there, to everyone in it, and replaces a World skill with the same id in that project. Because the instructions are a document, editing a skill is a document edit: it syncs, keeps its history and names who changed it.

Removing a skill takes it out of the catalog and keeps the document that holds its words. The document moves to a retired-skills folder, so nothing you wrote is lost.

An app can bring a skill with it: how to use the app and its records. It ships as a SKILL.md beside the app's package.json and becomes the app's skill document when the app is pushed.

Using it as you build

Write down how your agents should write, review, test and ship. Set standing instructions from the command line, for the World or for one project:

mod-next skills instructions --content "Use British spelling. Run the tests before saying it works."
mod-next skills instructions --project <projectId> --file AGENTS.md

Add a skill with a description of the task it is for. The description is what the agent chooses on, so describe the task, not the document:

mod-next skills add <projectId> "Writing plans" \
  --description "Writing or restructuring a plan document" --file plans.md
mod-next skills list
mod-next skills rm <skillId>

To keep a checkout's AGENTS.md in step with Mod, mod-next skills sync <projectId> writes the Mod block into it.

Agents use the same operations as tools. register_skill adds or updates a skill, with scope set to world or project. world_instructions reads or replaces the standing instructions; a set replaces the whole text, so read before you write. To change a skill's text, an agent uses patch_document on its document rather than registering it again. In the composer, type / to pick a skill for one message yourself.

For an app, put a SKILL.md beside its package.json. See apps.

Limits

• Turning a skill off without removing it, and keeping published revisions you can roll back to, are designed but not built (RFC 0327). soon
• A World skills library page, and exporting and importing skills between Worlds. soon