# Skills

> One registry of everything an agent can do: four execution kinds behind one contract, a catalogue you can read, organisation-authored skills, and a marketplace whose access rules are re-checked at dispatch

Source: https://aipril.dev/docs/harness/skills

## One registry

A skill is a declared capability. All of them live in a single registry - contract, registry, loader,
adapters, bootstrap - and the API that lists them reads that registry, not a maintained list.

The catalogue is therefore derived from what is installed, with real parameters, at the moment it
lands.

## Four execution kinds, one contract

| Kind | Executes as | Used for |
|---|---|---|
| `action` | A direct in-product operation | Filtering rows in a view, extracting facts from text |
| `workflow` | A durable orchestration | Anything consequential - inherits retry, compensation, persisted history |
| `agent-tool` | A thin alias over a tool in the tool plane | One operation reachable from chat, MCP and a workflow without three implementations |
| `mcp-proxy` | JSON-RPC forwarded to an external MCP server | Third-party capability installed into an organisation |

The kinds differ in execution only. Description, listing, permission checks, risk classification and
audit are shared.

## What is in the catalogue

Around two dozen authored skills ship, in this distribution:

| Kind | Count | Examples |
|---|---|---|
| `action` | 4 | `filter_rows`, `extract_facts_from_text`, `notify_slack`, `notify_telegram` |
| `workflow` | 10 | `create_bpm_process`, `evidence_grounded_update`, `cross_record_dedup` |
| `agent-tool` | 9 | `data.query` / `data.get_schema` / `data.list_models`; `bpm.get_task`, `bpm.get_task_status`, `bpm.get_tasks_text`; `ledger.balance`; `workbook.read_rows`; `dashboard.create` |
| `mcp-proxy` | Installed per organisation | Third-party capability from the marketplace |

Worth reading off that table: **process creation is a `workflow`, not an `action`.** Creating a
business process touches several stores and can fail halfway, so it runs durably with compensation
instead of as a best-effort call, and the same reasoning puts evidence-grounded updates and
cross-record deduplication there.

The `agent-tool` entries are thin aliases: `data.query` is the same operation the dashboards use, and
`bpm.get_task` is the same connector operation orchestration calls. One implementation, three
surfaces.

## Organisation-authored skills

An organisation can author its own skills; they become callable by the relevant agent instead of
sitting in a catalogue as documentation. Tool definitions are validated against strict-validating
providers, so a malformed name or a duplicate declaration fails at authoring instead of degrading
tool-calling at runtime.

A skill declares its name, its parameters with types, its execution kind, its risk classification and
its access level. Those five fields are what let the same entry be offered to a model, rendered in a
catalogue, filtered per role, gated at dispatch and recorded on the trail without any per-skill code
in any of those five places.

## Authoring one

A skill is authored the way an application is: **by an agent through MCP tools, with a person
approving and activating.** There is no paste-the-JSON form, because a hand-written manifest is the
thing that goes stale.

| Step | Tool | What happens |
|---|---|---|
| 1 | `skill.scaffold` | Creates the catalogue entry and a starter draft for the chosen kind. Idempotent. |
| 2 | `skill.write` | Overwrites the draft manifest and bundle. A skill package is one manifest plus one bundle, not a file tree. |
| 3 | `skill.validate` | Compile-checks the draft. A `workflow` draft is checked against the capabilities it is actually allowed to call; an `mcp-proxy` draft is schema-checked on its tool list and configuration fields. |
| 4 | `skill.version` | Validates, then copies the draft into an **immutable** version row under semver that must exceed every prior version, and bumps the catalogue's latest. |

`skill.list` and `skill.get` read the catalogue - slug, name, latest version, status, published
versions and the current draft.

Three properties of that flow are deliberate:

- **The draft survives publishing.** Versioning copies; it does not consume. The working state is
  still there for the next iteration.
- **A version is immutable.** What was published is what installs, and it cannot be edited under an
  installed base.
- **Authoring is separate from installing.** All authoring tools are administrator-only, and there is
  no install tool on the MCP surface at all: an agent authors, a tenant administrator activates
  through the product. The two authorities do not merge.

The tool descriptions themselves carry rules the authoring agent must follow - read the design before
authoring, present the manifest for approval before publishing a version, never reference a process
definition that has not been published. The constraint travels with the tool instead of living in a
prompt somebody has to remember to include.

**A quicker path for one organisation.** A skill that is only ever for you does not need the
catalogue: an administrator creates it directly in your own organisation, and it becomes callable by
the relevant agent immediately. The catalogue is for distribution, not for authoring.

## Marketplace

Skills are published to a platform catalogue, reviewed by a platform administrator, and installed by
an organisation administrator into their own organisation. Both `workflow` and `mcp-proxy` kinds
install. An `mcp-proxy` installation stores its configuration encrypted and dispatches over JSON-RPC
to the configured endpoint.

- **Manifest access is enforced end to end.** A skill marked administrator-only is resolved as such,
  filtered out of a non-administrator's tool list, and **re-checked at dispatch**.
- **An organisation-supplied endpoint is treated as untrusted input.** Outbound calls are hardened
  against server-side request forgery through the same mechanism as every other
  administrator-supplied URL on the platform.
- **Credentials reuse the platform's integration machinery** - OAuth2-backed storage and refresh -
  and not a second credential store.

Every proxied call is written to the audit trail. See [The decision trace](https://aipril.dev/docs/harness/traces.md).

## Why the registry, not the agent

Capability is added as a registry entry with declared parameters, a declared risk classification and
the standard audit path. The agent is unchanged. That is what allows one
[gate](https://aipril.dev/docs/harness/invocation.md) and one permission mechanism to cover every capability instead of
one policy per feature.

## Related

- [Tools and MCP](https://aipril.dev/docs/harness/tools-and-mcp.md) - the tool plane a skill aliases into.
- [Agents that act, not guess](https://aipril.dev/docs/harness/agents.md) - the same catalogue described for a business
  reader, with examples.
- [Connectors](https://aipril.dev/docs/platform/integrations/connectors.md) - the typed operations a workflow skill calls.
- [Applications](https://aipril.dev/docs/apps/under-the-hood.md) - the authoring model skills follow, one artifact kind
  over.