Core concepts

Airskills has three concepts you need to know.

Skill

A skill is one SKILL.md file (plus any supporting files it references). It teaches your AI agent how to do one thing — review PRs in your house style, write a release email, follow your commit message conventions.

Every skill belongs to exactly one owner — either you (a personal skill) or an organization (a team skill). It cannot belong to both.

Skillset

A skillset is a curated group of skills you install as one unit. Two ways they show up:

1. You curate them yourself to install in different places. One skillset for your laptop's coding setup, another for the writing machine, a third for the work repo where you only want a narrow slice. Same skills can appear in more than one — a skillset is a grouping, not a folder.
2. Your team curates them on your behalf. An admin builds a "backend joiner" or "customer support" skillset and assigns it to you. Your next airskills sync pulls every skill in it — no chasing, no install instructions, no decisions you didn't need to make.

airskills add chrismdp/backend-starter

If backend-starter is a skillset, that command installs every skill in it. You don't need to know which skills are inside — you just get the set.

Skillsets are owned by a user or an organization, same one-owner rule as skills.

Skills inside a skillset are still independent. If you've installed a skillset and decide you don't want one of the skills inside it, airskills rm removes that single skill from your machine. The skillset still exists for everyone else.

Organization

An organization is your team's shared account. Skills and skillsets can belong to it. Anyone you add as a member gets access to the organization's skills.

Organizations are where rollout and curation live. When you want a skill to be the team's standard rather than your standard, you transfer it from your personal account into the organization. See transfer.

The team's copy is the source of truth — but each member can still keep their own local tweaks via incorporation. The shared version keeps moving forward; each member chooses what to bring across when it does.

The rule of ownership

• A skill is owned by exactly one user or one organization. Never both, never neither, never more than one.
• A skillset follows the same rule — one owner, never shared ownership.
• When a skill moves between a user and an organization, it is a transfer — a deliberate, visible handoff.

This rule keeps the model simple: for any skill, there is exactly one person or team who can edit it, and exactly one URL where it lives.

Common situations

You wrote a skill and your team wants it

Transfer it to the organization. Everyone on the team automatically gets access. Admins edit the canonical copy directly; other members propose changes by suggesting them back, and the admins decide what to take. Each member can also keep local tweaks of their own and pull in the team's changes when they want to.

You want every new backend joiner to have the same five skills

Put them in a skillset, then have the organization assign it to new members. They get the whole set on their next airskills sync — the team curates on their behalf.

You want a different set of skills on your work laptop than your personal one

Build two skillsets and install one on each machine. Skillsets are how you hold "the right set of skills for this place" without hand-picking each time.

You added someone else's skill and want it on all your machines

A logged-in airskills add <owner>/<skill> subscribes you to that skill: the install is recorded against your account, so it follows you to your other machines on their next airskills sync — without a copy you have to maintain. It stays one skill, tracking the original; if you edit it, your changes overlay locally (backed up to your account). It shows in airskills list as "added from <owner>", never as one of your own. airskills rm unsubscribes it everywhere; rm --keep-remote keeps the subscription. If the owner later deletes the skill or makes it private, your local copy is saved as your own so you don't lose it.

A teammate leaves the company

Skills owned by the organization stay with the organization. Skills the teammate owned personally leave with them; if any were "unofficial team standards", ask them to transfer those into the organization before they go.

---

Deep dive: how ownership is enforced

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

Every skill row has exactly one of user_id or org_id set (never both, never neither). Skillsets follow the same pattern via an owner_user_id XOR owner_org_id check constraint.

Database-level RLS (row-level security) policies are written against those columns, so the API cannot accidentally return an organization skill to a non-member, or let a user edit a skill they don't own.

Organization membership lives in the memberships table, keyed on (user_id, org_id, role). It is not stored on profiles.org_id — that column is deprecated and should not be used for new features.

When an organization assigns a skillset to a member, a row is written into member_skillsets (user_id, skillset_id). The CLI's sync path reads this table to decide which skills to pull for you automatically.

When the CLI pushes a skill it checks your active organization context to decide whether the push lands in your personal namespace or the organization's. The client never gets to choose; the server derives it from the skill's current user_id / org_id and rejects any mismatch.