Under the hood

You don't need to read any of this to use airskills. The pages here are for when something looks odd, when you're extending the system, or when you're curious about why a particular decision was made.

What's here

• How skills are named — slug rules, what the server enforces, and the difference between display name and identity.
• The name == slug invariant — why SKILL.md's name: field must equal the directory name, and how the CLI enforces it.
• Commit DAG — every push is an immutable content-addressed commit. How history works, how rewinds and transfers fit in.
• How sync state works — the local marker file, the cross-state classifier, and the schema of .airskills-sync.

When you'd actually read this

• Two machines disagree about a skill — start with sync state to understand what each marker says.
• A skill won't push — likely a name/slug invariant failure.
• Old version mysteriously came back — the commit DAG explains how rewinds and transfers work.
• Building a tool against airskills — these pages document the contracts more precisely than the CLI's user-facing wording.

For the user-facing model, see Concepts.