Skills teach the agent how and when to use tools. Each skill is a directory containing a SKILL.md file with YAML frontmatter and markdown instructions. Apus loads skills from several roots in a defined precedence order.

Create your first skill

Skills live in your workspace `skills/` folder:

```bash
mkdir -p ~/.apus/workspace/skills/hello-world
```

You can group skills in subfolders for organization — the skill is still
named by the `SKILL.md` frontmatter, not the folder path:

```bash
mkdir -p ~/.apus/workspace/skills/personal/hello-world
# skill name is still "hello-world", invoked as /hello-world
```

The frontmatter defines metadata; the body gives the agent instructions.

````markdown
---
name: hello-world
description: A simple skill that prints a greeting.
---

# Hello World

When the user asks for a greeting, use the `exec` tool to run:

```bash
echo "Hello from your custom skill!"
```
````

Naming rules:
- Use lowercase letters, digits, and hyphens for `name`.
- Keep the directory name and frontmatter `name` aligned.
- `description` is shown to the agent and in slash-command discovery —
  keep it one line and under 160 characters.

```bash
apus skills list
```

Apus watches `SKILL.md` files under skills roots by default. If the
watcher is disabled or you are continuing an existing session, start a new
one so the agent receives the refreshed list:

```bash
# From chat — archive current session and start fresh
/new

# Or restart the gateway
apus gateway restart
```

```bash
apus agent --message "give me a greeting"
```

Or open a chat and ask the agent directly. Use `/skill hello-world` to
invoke it explicitly by name.

Create a personal skill on a shared Gateway

For a skill that should follow your signed-in profile rather than belong to an agent workspace, use Plugins → Skills → My skills. Create or import the SKILL.md bundle there, then review the saved revision and activation result. You do not need host shell access or permission to edit shared Gateway settings.

You can also ask the agent to create or improve a personal skill. Its skill_workshop tool uses the Gateway's authorized library service; it does not write managed revision directories directly. The result names the published revision and explains when the session can use it. Ask explicitly to use the new revision in the current session or share it with the team.

The single-admin default remains the workspace workflow above. Extra channel identities for the same operator do not turn a personal installation into a team setup. See personal skills and revisions for ownership, sharing, storage, and session behavior.

SKILL.md reference

Required fields

Optional frontmatter keys

For gating fields (requires.bins, requires.env, etc.) see Skills — Gating.

Using {baseDir}

Reference files inside the skill directory without hardcoding paths — the agent resolves {baseDir} against the skill's own directory:

Run the helper script at `{baseDir}/scripts/run.sh`.

Adding conditional activation

Gate your skill so it only loads when its dependencies are available:

---
name: gemini-search
description: Search using Gemini CLI.
metadata: { "apus": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }
---

| Key | Description |
| --- | --- |
| `requires.bins` | All binaries must exist on `PATH` |
| `requires.anyBins` | At least one binary must exist on `PATH` |
| `requires.env` | Each env var must exist in the process or config |
| `requires.config` | Each `apus.json` path must be truthy |
| `os` | Platform filter: `["darwin"]` (or `["macos"]`), `["linux"]`, `["win32"]` |
| `always` | Include on a compatible OS even when `requires.*` checks fail |

Full reference: [Skills — Gating](/tools/skills#gating).

Wire an API key to a skill entry in `apus.json`:

```json5
{
  skills: {
    entries: {
      "gemini-search": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
      },
    },
  },
}
```

The key is injected into the host process for that agent turn only.
It does not reach the sandbox — see
[sandboxed env vars](/tools/skills-config#sandboxed-skills-and-env-vars).

Learned skills (Skill Workshop)

Agents also write their own skills through Skill Workshop. Those learned skills apply immediately and keep their previous versions, so any change can be undone. Inspect and manage them from the CLI:

apus skills workshop list
apus skills workshop changes
apus skills workshop show hello-world
apus skills workshop archive hello-world --reason "Replaced by greeting"
apus skills workshop restore hello-world

See apus skills workshop for every option.

Publishing to ClawHub

An owner is a ClawHub publisher handle, such as @alice or @your-org. Your account has a personal owner. Organization owners can have members with owner, admin, or publisher roles; all three roles can publish. Choose your personal owner or an organization where you have publisher access.

Make sure `name`, `description`, and any `metadata.apus` gating fields
are set. Add a `homepage` URL if you have a project page.

```bash
npm i -g clawhub
clawhub login
```

```bash
clawhub skill publish ./path/to/hello-world
```

Add `--version <version>` or `--owner <owner>` to override the inferred
version or publish under a specific owner. See
[ClawHub — Publishing](/clawhub/publishing) and
[ClawHub CLI](/clawhub/cli) for the full flow, owner scoping, and other
maintenance commands (`clawhub sync`, `clawhub skill rename`, ...).

Best practices

Related

Loading order, gating, allowlists, and SKILL.md format.

Skills your agent saves and updates on its own, with undo.

Full `skills.*` config schema.

Browse and publish skills on the public registry.

Plugins can ship skills alongside the tools they document.

How the command a skill registers is invoked and gated.