---
title: Abilities
description: "Marketplace ability packages your agent installs and runs: the catalog, versions, install and sync."
---

# Abilities

Your NOLGIA Agent installs and runs ability packages from a marketplace published by admins. Browse the catalog, inspect an ability, then install and sync the packages you need.

## Catalog and installs

<!-- gen:endpoints tag=Abilities -->
| Method | Path | What it does |
| --- | --- | --- |
| [GET](../api/#tag/abilities/get/agent/abilities) | `/agent/abilities` | List the abilities installed for the current user's agent. |
| [POST](../api/#tag/abilities/post/agent/abilities/{slug}) | `/agent/abilities/{slug}` | Install a published ability for the current user's agent (applied on the next ability sync). Requires the ability's entitlement (`min_tier`). Optionally pins the install to an exact published version; without a pin the install tracks the latest published version (the default). |
| [DELETE](../api/#tag/abilities/delete/agent/abilities/{slug}) | `/agent/abilities/{slug}` | Uninstall an ability from the current user's agent. |
| [GET](../api/#tag/abilities/get/agent/abilities/events) | `/agent/abilities/events` | Stream ability version publishes for the current user's agent over Server-Sent Events. |
| [GET](../api/#tag/abilities/get/abilities) | `/abilities` | List published marketplace abilities (metadata only — content is never included in listings). Customers see the public catalog; admin accounts also see private abilities. |
| [POST](../api/#tag/abilities/post/abilities) | `/abilities` | Publish a new ability version (admin only; upserts the ability by slug, versions are immutable). |
| [GET](../api/#tag/abilities/get/abilities/{slug}) | `/abilities/{slug}` | Get a published ability's detail. |
| [GET](../api/#tag/abilities/get/abilities/{slug}/content) | `/abilities/{slug}/content` | Download a published version's package content (base64 tar.gz) — the latest version by default, or the exact version named by `version` (how a pod materializes a pinned install). Entitlement-gated — the caller's subscription must satisfy the ability's `min_tier`. |
<!-- /gen -->

## The ability record

<!-- gen:fields schema=Ability -->
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | Marketplace identity of the ability; also the install directory name under `$HERMES_HOME/skills/` (the on-disk install root is unchanged for backward compatibility). |
| `name` | string | Yes |  |
| `description` | string | Yes |  |
| `required_env` | array of string | Yes | Environment variables the ability expects on the agent pod. |
| `credit_cost_hint` | string | Yes | Free-text hint of how the ability spends credits. |
| `min_tier` | string | Yes | Minimum subscription tier required to install or download this ability's content. Empty means free for any account. |
| `visibility` | `AbilityVisibility` | Yes |  |
| `entitled` | boolean | Yes | Whether the calling account may download this ability's content (subscription satisfies `min_tier`, or admin). Listings are metadata-only; content download is refused (402) when false. |
| `access` | `AbilityAccess` | Yes |  |
| `price_cents` | integer, nullable | No | For `premium_addon` abilities, the add-on price in cents. `null` for `included` abilities. Metadata only — no purchase flow enforces it yet. |
| `interval` | `AbilityInterval`, nullable | No | For `premium_addon` abilities, the billing interval of `price_cents`. `null` for `included` abilities. |
| `has_code` | boolean | Yes | True when the package carries a code payload — any file beyond the manifest files (`SKILL.md` and `ability.json`). Computed at publish time. Drives the marketplace "Package" vs "Ability" (instructions-only) kind badge. |
| `latest_version` | string | Yes | Latest published version by SEMVER ordering (highest major.minor.patch wins), not by publish time — a 1.0.1 published after a 1.2.0 does not become latest.… |
| `created_at` | string | Yes |  |
| `updated_at` | string | Yes |  |
<!-- /gen -->

> [!NOTE]
> Publishing is admin-only and versions are immutable. Holding an ability with `visibility=private` removes it from the catalog without breaking existing installs.

## From the CLI

These subcommands are listed by `nolgia ability --help`.

| Subcommand | What it does |
| --- | --- |
| `list` | List the marketplace catalog visible to this account |
| `show` | Show one marketplace ability |
| `installed` | List abilities installed for this account's agent |
| `install` | Install a marketplace ability for this account's agent |
| `uninstall` | Uninstall a marketplace ability from this account's agent |
| `sync` | Materialize installed abilities into a skills directory (what the agent pod's initContainer runs on boot) |
| `init` | Scaffold a new ability authoring directory (ability.json, SKILL.md, payload/) |
| `pack` | Validate an ability authoring directory and assemble the publishable package |
| `publish` | Publish an ability package directory to the marketplace (admin only) |
| `help` | Print this message or the help of the given subcommand(s) |

:::cards
- [Agent Sessions API](./agent-api.html) icon=spot-agent: Run persistent conversations with your agent.
- [The operator model](./operator.html) icon=spot-jobs: Configure your agent and observe installed versions.
- [The CLI](./cli.html) icon=spot-terminal: Install the CLI and script your workflow.
:::