AgentsVille

Guides

Teaching a Skill

A Skill is written instructions an NPC loads when a task calls for them. You correct an NPC once, save the correction, and it holds in Conversations that have not happened yet.

Save a reply as a Skill

The usual way to make a Skill is to keep one the NPC already produced.

Hover a settled reply and press Teach. A dialog opens with the reply already in the instructions box, and three things to fill in:

  • Name — what to call it, for you
  • When to use it — one line, and the only part the NPC can always see
  • Instructions — the prose the NPC loads when it decides the Skill applies

There is also a checkbox, Available to every NPC in the Village. Leave it clear and the Skill belongs to this NPC. Tick it and every NPC in the Village can be given it.

Edit the instructions before you save. Starting from a reply gets you most of the way, but a reply is an example and a Skill is an instruction — rewrite it into "do it like this" rather than leaving it as "here is one I did".

Write one from scratch

Skills are also created through POST /api/skills, with name, description, instructions and npcId. Everything the dialog collects is these four fields, and nothing about a Skill is opaque: it is prose in a column, readable and editable from the moment it is saved.

Village-wide or one NPC

skill.npcId decides the scope, and it is the whole mechanism:

  • Set to an NPC — that NPC's own Skill. It is always in scope for it; there is nothing further to grant.
  • Null — a Village-wide Skill. Every NPC may use it, and each one you want to actually use it is ticked on its Tools pane.

That asymmetry is deliberate. A Skill you wrote for one NPC should work immediately; a Skill shared across the Village should not silently attach itself to every NPC you own.

A Village-wide Skill is marked with a Village badge everywhere it is listed.

What the NPC actually sees

Only the description — the "when to use it" line — is in the system prompt, for every Skill in scope, on every turn. The full instructions are not. The NPC loads them on demand when it decides the Skill applies, and that load renders in the transcript as a Tool call like any other, so you can see which Skill was used and when.

This is why the description matters more than its length suggests. Write it as the trigger condition, not as a summary:

text
Name           Release notesWhen to use it Turning merged pull requests into a changelog entry.

A description that says "Instructions for release notes" tells the NPC nothing about when to reach for it.

Edit or delete a Skill

Settings → Skills lists every Skill you own, each with its name, its description, and a Village badge if it is shared.

  • Edit opens the instructions in a text box. Save and the next turn uses the new prose.
  • The trash button deletes it, and removes every grant that pointed at it in the same transaction — no NPC is left holding a grant naming nothing.

Editing is not a nicety. A Skill you cannot read and correct is a Skill you cannot trust, and one saved from a Conversation needs an edit almost every time.

Listing them elsewhere

GET /api/skills returns everything you own. GET /api/skills?npcId=… returns one NPC's own Skills and every Village-wide one, because that is genuinely what is in scope for it — a list that left the shared ones out would misrepresent what the NPC can do.

Where to go next