Why the folder name matches the skill name

If you are just using Airskills, the CLI handles this for you and you'll never notice. This page is here for anyone writing tooling that creates skills on disk, or debugging an unexpected error.

The rule

The name: field inside a skill's SKILL.md must equal the folder name that contains it. For example:

~/.claude/skills/code-review/SKILL.md    contains    name: code-review
~/.claude/skills/release-email/SKILL.md  contains    name: release-email

Any other combination is invalid. The CLI catches and fixes mismatches on push; the server rejects them on ingest.

Why it exists

Every AI agent that reads a SKILL.md file does so out of a folder. For the metadata inside to line up with how the agent addresses the skill ("use the code-review skill"), the two names have to be the same. Otherwise you get confusing situations like the file saying name: foo but everyone calling it bar.

It also means any agent can reconstruct the full addressing of a skill from its folder alone, without having to call an API. The skill is self-describing.

What the CLI does

When you run airskills push:

1. For each skill folder, the CLI reads the name: field in SKILL.md.
2. If name: does not match the folder name, the CLI rewrites SKILL.md so that it does — silently, before anything goes to the server.
3. The push then goes through with a consistent folder/name pair.

When you run airskills mv <old> <new>:

1. The local folders are renamed across every detected agent.
2. The name: field in each SKILL.md is rewritten to match.
3. The server is told the new name.

You should not need to hand-edit the name: field. Rename the folder, or use airskills mv, and the CLI does the rest.

For organization skills

Organization skills have a prefix on their public slug (e.g. acme-code-review) but the name: field inside is still just the base (code-review). The folder on disk is the base name too. The prefix is an addressing concern, not a file-name concern.

If you hit this as an error

You will only see this as an error if something non-CLI has written to your skills folder and left a mismatch — for example, you hand-edited the name: field, or you copied a skill folder from one place to another without renaming the name: field.

The fix is usually: airskills push will rewrite name: to match the folder, or you can edit the name: field yourself to match.

---

Deep dive: where the invariant is enforced

For curious developers — skip if you just want to use it.

The invariant is enforced in three places:

1. CLI push (cmd/push.go) — compares folder name vs SKILL.md name: and rewrites the file before upload.
2. Server ingest — the API validates name == folder-derived slug base on every write. A mismatch returns 400 name_mismatch with an explanatory body.
3. Server write policies — a CHECK constraint on the skills table guarantees no row can exist with a name that doesn't match the addressed slug base. Migration 024 added this; all subsequent writes go through it.

The algorithm for "base of slug" is: if the slug is organization-prefixed (<organization-slug>-<base>), the base is everything after the first hyphen that matches a known organization slug. Otherwise the slug is the base unchanged. This is handled by the same slugify() helper on both sides.

Both CLI and server agree on the same rule so pushes can round-trip without surprises.