Skip to main content
A skill is a folder of instructions and supporting files the agent can load to perform a specialized task. Each skill is identified by a slug and described by a SKILL.md manifest. Skills come from three sources — ones you upload to your account, ones discovered in a project’s GitHub repository, and ones Aether provides to every workspace — and are materialized into the workspace so the agent can read them.

​
The SKILL.md Manifest

Every skill is a directory containing a SKILL.md file. That file must begin with YAML frontmatter, and the frontmatter must include both a name and a description:
SKILL.md
The contract is strict and validated when you upload or index a skill:
  • name is required and must exactly match the skill’s slug.
  • description is required.
  • The file must start with a --- frontmatter block.
A slug is 1–64 lowercase alphanumeric or dash characters and must start and end with an alphanumeric character.

​
User, Repo, and Aether Skills

User skills are saved to your account and available across all your projects. Upload them with the aether skill command family — push a local folder, or sync to bulk-import skills discovered in .agents/skills and .claude/skills (in the current repo) and ~/.claude/skills, ~/.agents/skills, and ~/.codex/skills (in your home directory). A skill bundle may contain up to 1000 files, with a 5 MB per-file and 50 MB total uncompressed limit. User skills are encrypted at rest. Repo skills are discovered automatically. When a project is linked to a GitHub repository, Aether indexes any .agents/skills/<slug>/SKILL.md files on the repository’s default branch and offers those skills to the agent for that project. Aether skills are maintained by Aether and ship to every workspace, whatever the project. They are read-only and always current with the platform. Today’s set is Aether’s own aether-workflow plus a selection of Matt Pocock’s engineering skills (MIT), vendored unchanged with their MIT notice: grill-with-docs, grilling, domain-modeling, codebase-design, research, prototype, wayfinder, triage, to-spec, to-tickets, implement, tdd, and code-review (the set is closed under the skills they call), and Cursor’s thermo-nuclear-code-quality-review from the cursor-team-kit plugin (MIT), an unusually strict maintainability review of a branch’s changes. The rules for running them on agents without a Skill tool, and the tracker, triage-label, and domain-docs configuration the planning skills expect (upstream’s setup-matt-pocock-skills interview is not shipped; Aether provides that configuration itself), are part of every task’s instructions rather than a skill file, so nothing in a workspace can change them. Each one can be turned off for your account under Settings → Skills or with the default skills API; a skill you turn off is left out of your workspaces and your project skill lists until you turn it back on. A skill another enabled Aether skill calls stays on until you turn that one off too (the API reports who needs it in required_by and refuses the toggle), so a workspace never receives a skill whose calls point at a missing one. A user skill with the same slug as an Aether skill replaces it in your workspaces, except aether-workflow, whose slug is reserved as Aether’s own.

​
Slug Shadowing

A project sees a single, combined skill set. When a repo skill and a user or Aether skill share the same slug, the valid repo skill wins — it shadows the other skill of the same slug for that project. This lets a repository pin a project-specific version of a skill without you having to remove your personal one. Likewise a user skill shadows an Aether skill of the same slug (other than the reserved aether-workflow), so you can replace a default with your own version by uploading one under its name. Reserved slugs (aether-workflow and the mobile-testing skills) cannot be shadowed by a repo skill either: a repo skill under one of those names is indexed as invalid with a reserved_slug diagnostic.

​
How Skills Reach the VM

When a workspace is provisioned, your skills are streamed into a canonical skills directory in the VM at ~/.aether/skills/<slug>/. This directory is wiped and rebuilt on each provision, so deleting a skill removes it from the workspace on the next run. The canonical directory is then symlinked into each agent’s own config location (for example ~/.claude/skills), so whichever agent provider you run can read the same set.

Skills Guide

Authoring, uploading, and syncing skills with the CLI.

GitHub Integration

Linking a repo so its skills are indexed.

Skills API

List, upload, and delete skills over the API.

Agents & Models

The agents that consume your skills.