# Skills

Reusable capability packages. Install from the Marketplace or build your own.





A skill is a packaged capability the agent can invoke on demand: send a Slack DM, draft a Linear issue, summarise a PR, run a database query. Each skill is a self-contained folder with instructions, optional helper scripts, and a description that tells the agent when to use it.

Skills are managed at the org level under [Settings → Artifacts](https://app.nairi.ai/settings/artifacts?tab=skills) and attached to specific agents from the agent editor.

## Two ways to add a skill [#two-ways-to-add-a-skill]

### From the Skill Marketplace [#from-the-skill-marketplace]

The [Skill Marketplace](https://app.nairi.ai/settings/skill-marketplace) is powered by [skills.sh](https://www.skills.sh) — the open catalogue of agent-skill packages — and surfaced inside the Nairi dashboard so you can browse, search, and install in one click.

1. Open **Settings → Skill Marketplace**.
2. Find a skill. Click **Install**.
3. The skill now lives at org level. Any agent in your org can attach it.
4. Attach it to an agent: [Fleet](https://app.nairi.ai/agents/fleet) → the agent → tick the skill in the **Skills** section → **Save & Redeploy**.

Removing an installed skill from your org: open [Settings → Artifacts](https://app.nairi.ai/settings/artifacts?tab=skills), find the skill in the list, click the trash icon. The skill must not be attached to any agent at the time you delete it.

### Custom skills (your own package) [#custom-skills-your-own-package]

For internal tools, private CLIs, or anything the Marketplace doesn't cover. Build a skill package and upload it.

1. Open [Settings → Artifacts](https://app.nairi.ai/settings/artifacts?tab=skills).
2. Click **Upload Skill**.
3. Pick a `.zip` or `.skill` file.
4. The skill appears in the list. Attach it to agents the same way you would a Marketplace skill.

To ship a new version, open the skill's row, click **Update**, and upload the new file. Agents pick up the new version on their next redeploy.

## What's in a skill package [#whats-in-a-skill-package]

Nairi skills follow the open [**agentskills.io**](https://agentskills.io) specification — the same skill package format used across the agent-skill ecosystem. See [agentskills.io](https://agentskills.io) for the canonical spec; the rest of this page covers the parts that matter for using skills in Nairi.

A skill is a folder with at least one file: `SKILL.md`. Helpers and references are optional.

```
my-skill/
  SKILL.md
  scripts/
    do-thing.sh
  references/
    cheatsheet.md
```

Zip the folder (not its contents — the zip should contain a single top-level directory) and name it `my-skill.zip` or `my-skill.skill`.

<Callout type="warn">
  The archive must contain a single root directory. A zip of multiple loose files at the top level will fail to upload. macOS users: `__MACOSX/` and `.DS_Store` entries are ignored automatically.
</Callout>

## `SKILL.md` structure [#skillmd-structure]

YAML frontmatter followed by markdown body.

```markdown
---
name: post-to-slack
description: Send a message to a Slack channel via webhook. Use when the user asks to "post", "send", or "share" to Slack.
allowed-tools:
  - Bash
  - Read
version: 1.2.0
---

# How to post to Slack

1. Read the webhook URL from `SLACK_WEBHOOK_URL`.
2. Build the message body.
3. POST it via `curl`.

...
```

| Field           | Required | Purpose                                                                                       |
| --------------- | -------- | --------------------------------------------------------------------------------------------- |
| `name`          | yes      | Kebab-case identifier. Used internally.                                                       |
| `description`   | yes      | What the skill does **and when to use it**. The agent reads this to decide whether to invoke. |
| `allowed-tools` | yes      | Whitelist of tools the skill can call (`Bash`, `Read`, `Write`, etc.).                        |
| `version`       | no       | Semver. Bump it when you ship changes.                                                        |

### Writing a description the agent will actually use [#writing-a-description-the-agent-will-actually-use]

The single biggest factor in whether a skill gets called is the `description`. The agent does not read the body until it has decided the skill applies, and that decision is made from the description alone.

Good descriptions are concrete:

* ✅ &#x2A;"Open a Linear ticket. Use when the user asks to file a bug, log a feature request, or 'create a Linear issue'."*
* ❌ &#x2A;"Linear integration."*

Include trigger phrases the agent should recognise. If the skill replaces something the agent would otherwise do worse, say so explicitly.

See the API reference for the full package spec: [Skills package requirements](/api/skills/package-requirements).

## Giving a skill credentials via vaults [#giving-a-skill-credentials-via-vaults]

Most skills that do anything useful need an API key. The standard wiring is to keep the skill credential-agnostic (it just reads `$CCASECRET_<NAME>` from the environment) and let the operator attach a [vault](/help/vaults) on the agent.

A `vercel-deploy` skill:

```bash
# scripts/trigger-deploy.sh
curl -X POST https://api.vercel.com/v13/deployments \
  -H "Authorization: Bearer $CCASECRET_VERCEL_API_KEY" \
  -d '{"name": "my-project"}'
```

Paired with a vault that has a `VERCEL_API_KEY` secret pinned to `api.vercel.com`. Attach both to the agent and the skill works.

The benefits of this split:

* **Skill authors don't see secret values.** A skill can be shared across orgs (or in the Skill Marketplace) without baking in anyone's key.
* **Secrets rotate without re-uploading the skill.** Update the vault value and the change propagates within \~2 minutes.
* **Domain pinning still applies.** The secret proxy enforces that `VERCEL_API_KEY` only ever leaves the container in a request to `api.vercel.com`.

See [Vaults & Secrets](/help/vaults) for the full setup walkthrough.

## Marketplace vs custom: when to pick which [#marketplace-vs-custom-when-to-pick-which]

* **Marketplace** is the right answer when the tool exists in our catalogue and a generic auth flow is acceptable. Updates ship automatically.
* **Custom** is right for anything proprietary, internal, or domain-specific. You own updates.

You can mix both. An agent can have a Marketplace skill and three custom ones attached at the same time.

## Skills as an alternative to MCPs [#skills-as-an-alternative-to-mcps]

Skills and [MCPs](/help/mcp) overlap. An MCP gives the agent a fixed set of tool calls it can invoke; a skill gives the agent a packaged playbook (markdown instructions plus helper scripts) it can run. For a lot of integrations, either approach works — and the choice comes down to how much control you want.

### Why reach for a skill instead of an MCP [#why-reach-for-a-skill-instead-of-an-mcp]

* **More control over the actions the agent can take.** An MCP exposes whatever tool surface the upstream server decided to expose, and you can't trim it. A skill is a script you wrote: it does exactly the operations you implemented, with whatever guardrails you put in. If the agent should only be able to *read* from a system, the skill simply doesn't include a write path.
* **More control over the agent's context.** MCP tool definitions, parameter schemas, and tool output formats are all set by the MCP server. A skill picks what to load into context and how to format it — useful for keeping the agent's context window focused on the fields that actually matter for the task.
* **More control over auth, retries, error handling.** Your script, your behaviour. Quirky pagination, rate limits, custom auth flows — you handle them however you want.
* **No "live connection" required.** MCPs run as long-lived processes or HTTP services. A skill is just a folder of files; the agent reads it when needed, runs the scripts when relevant, and that's it.

### Why reach for an MCP instead of a skill [#why-reach-for-an-mcp-instead-of-a-skill]

* **Functionality out of the box.** Pick a [Marketplace](/help/mcp#mcp-marketplace-composio-powered) integration, click connect, the agent can use it immediately. You write nothing.
* **No maintenance.** Schema changes, API deprecations, new endpoints — the MCP server handles them. With a skill, that's on you. When you update a skill, you re-upload the package.
* **Broad capability.** A general-purpose Linear MCP gives the agent access to *everything* in the Linear API. A skill typically covers one narrow workflow.

### A pragmatic path [#a-pragmatic-path]

Start with an MCP from the Marketplace to validate the use case quickly. If you outgrow it — you need a narrower tool surface, a different output format, or to compose multiple calls into one operation the agent reaches for as a single move — package the equivalent as a skill.

Skills and MCPs also compose. An agent can have the Linear MCP attached (general access to tickets) *and* a `weekly-digest` skill that uses that MCP plus your own template to produce the output you actually want.

## Related [#related]

* [agentskills.io](https://agentskills.io) — the open specification for skill packages
* [skills.sh](https://www.skills.sh) — the open catalogue that powers the in-app Marketplace
* [Adding skills to an agent](/help/building-agents/how-to-deploy#skills)
* [MCP Tools](/help/mcp) — for tool calls that need a live connection rather than a packaged script
* [API: Skills](/api/skills/overview)

***

*Can't find what you're looking for? Email [support@nairi.ai](mailto:support@nairi.ai).*