Skills

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 and attached to specific agents from the agent editor.

Two ways to add a skill

From the Skill Marketplace

The Skill Marketplace is powered by 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 → the agent → tick the skill in the Skills section → Save & Redeploy.

Removing an installed skill from your org: open Settings → Artifacts, 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)

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

1. Open Settings → Artifacts.
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

Nairi skills follow the open agentskills.io specification — the same skill package format used across the agent-skill ecosystem. See 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.

SKILL.md structure

YAML frontmatter followed by markdown body.

---
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`.

...

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:

• ✅ "Open a Linear ticket. Use when the user asks to file a bug, log a feature request, or 'create a Linear issue'."
• ❌ "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.

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 on the agent.

A vercel-deploy skill:

# 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 for the full setup walkthrough.

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 and MCPs 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

• 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

• Functionality out of the box. Pick a Marketplace 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

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

• agentskills.io — the open specification for skill packages
• skills.sh — the open catalogue that powers the in-app Marketplace
• Adding skills to an agent
• MCP Tools — for tool calls that need a live connection rather than a packaged script
• API: Skills

Can't find what you're looking for? Email support@nairi.ai.