> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Reusable instruction bundles the agent loads into the workspace, authored as SKILL.md folders.

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 two sources — ones you upload to your account, and ones discovered in a project's GitHub repository — 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`:

```markdown SKILL.md theme={null}
---
name: my-skill
description: One sentence describing when the agent should use this skill.
---

# My Skill

Instructions, examples, and any guidance the agent should follow.
```

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 Skills vs Repo Skills

**User skills** are saved to your account and available across all your projects. Upload them with the [`aether skill`](/guides/skills) 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` 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.

### Slug Shadowing

A project sees a single, combined skill set. When a repo skill and a user skill share the same slug, the **valid repo skill wins** — it shadows your user 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.

## 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](/concepts/agents-and-models) you run can read the same set.

## Related

<CardGroup cols={2}>
  <Card title="Skills Guide" icon="upload" href="/guides/skills">
    Authoring, uploading, and syncing skills with the CLI.
  </Card>

  <Card title="GitHub Integration" icon="github" href="/guides/github-integration">
    Linking a repo so its skills are indexed.
  </Card>

  <Card title="Skills API" icon="code" href="/api-reference/v1/skills/get-skills">
    List, upload, and delete skills over the API.
  </Card>

  <Card title="Agents & Models" icon="robot" href="/concepts/agents-and-models">
    The agents that consume your skills.
  </Card>
</CardGroup>