arizuko › concepts › skills

skills

A secret is a credential a skill can spend; a skill is the job that spends it. A skill is a directory of markdown the agent reads when it needs to do something specific — another set of files in the ant, exactly as page one promised. The agent ships with a built-in set and the operator can drop in more. The one thing to internalize: skills don’t fire on their own. An LLM won’t reliably notice a skill applies, so the agent calls one explicitly through /dispatch — discovery is a deliberate step, not magic.

what a skill is

One directory under ant/skills/. Every skill has a SKILL.md with YAML frontmatter and a body:

---
name: skill-name
description: one-line summary
triggers: [keyword1, keyword2]
---

Skill instructions here...

Names must match ^[a-z0-9\-]+$ — the seeder skips anything else. The body can be markdown plus any reference files (*.md) or executable helpers (*.sh, *.ts) that live next to SKILL.md.

built-in vs user skills

Two sources feed the agent’s skill list:

• Built-in. Everything under ant/skills/ in the arizuko repo — self, migrate, diary, find, oracle, persona, visual, and around 50 more. These ship inside the arizuko-ant Docker image and are copied into every new group by container.seedSkills(). See onboarding for the copy mechanism.
• User. A group can add its own skills under /home/node/.claude/skills/ (the per-group workspace mounted into the container). The agent loads them the same way; the only difference is they live in the group’s data dir, not the image.

Built-in skills get refreshed on every /migrate run; user skills are never overwritten.

discovery: dispatch is explicit

LLMs do not reliably auto-trigger skills by reading their descriptions. The agent runs /dispatch as the first step on each turn: dispatch scans every skill’s description + triggers, matches the current message, and tells the agent which skill to load. Without dispatch, skills sit there unused.

/reconcile handles the late case — if the agent produced output and then realized a skill applied, reconcile re-runs the work under the correct skill so the output doesn’t contradict the skill’s rules.

migration and versioning

The agent image carries a version number in ant/skills/self/MIGRATION_VERSION — a single integer. Every release that ships skill changes bumps this number. On agent startup, routd compares the image’s version against the group’s last-seen value:

• If higher, the agent runs /migrate, which copies new and changed skill files from the image into the group’s .claude/skills/ — preserving user skills, replacing built-ins.
• The same hook fires the release broadcast: the > blockquote at the top of the new CHANGELOG.md entry is extracted and posted into the chat. Skill update and announcement travel together — bumping the version is the single trigger.

Each version bump has a corresponding ant/skills/self/migrations/NNN-vX.Y.Z-summary.md file. The file’s existence is what fires the broadcast; an empty stub body is fine for docs-only releases.

go deeper

How a group gets its initial skill set: onboarding. Format rules and the per-skill layout: specs/1/B-extend-skills.md. The shipping flow that bumps MIGRATION_VERSION and writes a migration file: CLAUDE.md — “Shipping changes” section. What ships in each version: changelog.