AWORG

How-Tos

Build a skill

A skill is a Markdown file. Here's how to write one that changes what a Resident does.

What a skill is

A skill is a folder containing a SKILL.md. AWORG uses the standard Agent Skills format, so a skill written for another tool that uses SKILL.md will usually work as is.

my-skill/
  SKILL.md
  references/        (optional)
    palette.css
    checklist.md

SKILL.md starts with frontmatter, followed by the procedure:

---
name: my-skill
description: Builds dashboards in our house style. Use this whenever the owner asks for a chart, a dashboard, or any page that shows numbers.
version: 1.0.0
license: MIT
---

# Dashboards, our way

Use a 12-column grid, 24px gutters...

How the Resident uses it

  • The description of every switched-on skill is included with every message the Resident receives.
  • The body is read only when the Resident decides the skill applies, using its read_skill tool.
  • Files in references/ are read only when the body points to them.

So a dozen skills cost a dozen descriptions, not a dozen documents. That has two consequences:

  1. The description has to say when to use the skill. A description that says only what the skill is about won't get picked. Name the situations: "Use this whenever…"
  2. Put long material in references/. The body should be what's needed every time. Put lookup tables and long examples in files it can open when needed.

What makes a skill worth installing

This has been measured with real Residents, not guessed:

  • Process advice does nothing. "Plan first, test your work, use real content": the Resident already does these. A skill made of such rules produced no better results than no skill at all, and its restrictions made the work worse.
  • A point of view changes everything. Concrete values the model can't guess do make a difference: a palette in hex, a type scale in pixels, a section order, the commands for your deploy target, a check it wouldn't think of. Two skills for the same job, with different values, give two visibly different results. That's the reason to have a library of them.

Write down what you know that a capable newcomer wouldn't.

Try it locally

Copy the folder into your Aworg's home:

cp -r my-skill ~/.aworg/skills/

Skills are re-read on every message, so no restart is needed. Switch it on in the Skills pane and ask for something it covers.

Publish it

Zip the folder and upload it. See Publish a package.