# Overview

What skills are and how to package reusable capabilities for agents.



A **skill** is a packaged capability you upload to Nairi as a `.skill` or `.zip` archive. Skills bundle instructions, scripts, and reference material that an agent can load on demand — they're how you teach an agent to do something specific without bloating its base system prompt.

## What a skill looks like [#what-a-skill-looks-like]

A skill is a folder you zip up. The shape Nairi expects:

```text
my-skill/
├── SKILL.md       # instructions (required)
├── scripts/       # executables the agent runs (optional)
├── references/    # longer-form docs the agent loads on demand (optional)
└── assets/        # templates, images, sample data (optional)
```

**`SKILL.md`** is the entrypoint. It starts with YAML frontmatter — at minimum a `name` and a `description` — followed by markdown instructions the agent reads when it loads the skill.

```markdown
---
name: weekly-sales-report
description: Pull last week's sales data and format it as a customer-ready report. Use when a user asks for a weekly sales report.
---

# Weekly sales report

To produce the report:

1. Run `scripts/fetch-sales.sh` to pull last week's data.
2. Format the rows using `references/report-template.md`.
3. Return the formatted output.
```

Treat the frontmatter `description` like an LLM tool description: tell the agent **when to use the skill**, not just what it is. The agent reads descriptions to decide whether to load a skill at all.

The optional subdirectories are reached by path from `SKILL.md`:

* **`scripts/`** — bash, Python, or any executable the agent runs inside its container.
* **`references/`** — longer-form docs the agent only loads when needed (API references, glossaries, sample payloads). Keeps the base instructions short.
* **`assets/`** — static files scripts or instructions read at runtime (templates, sample data, images).

See [Package requirements](/api/skills/package-requirements) for the strict validation rules (size limits, name format, etc.).

## How it works [#how-it-works]

1. Author the skill locally — a folder with `SKILL.md` plus any helper files.
2. Zip it and upload with `POST /artifacts/skills` (multipart form data). Skill names must be unique within an organization. Max archive size is 32 MB.
3. Attach to one or more agents via [agent resources](/api/agent-resources/overview) (`entity_type: "agent_artifact_skill"`) and redeploy.
4. Update by uploading a new archive to the same skill ID. Delete with `DELETE /artifacts/skills/{id}`.

## When to use it [#when-to-use-it]

* **Package a customer-facing workflow into one reusable unit.** Onboarding flow, ticket-triage routine, report generation — bundle the instructions and scripts and let the agent invoke it by name.
* **Reuse the same workflow across many agents.** Write it once; attach it everywhere; keep base system prompts lean instead of pasting the same instructions into each.

## Skills vs. rules vs. MCP configs [#skills-vs-rules-vs-mcp-configs]

* **[Rules](/api/rules/overview)** — text instructions always present in the system prompt. Use for tone, policy, and broad guidance.
* **Skills** (this section) — capabilities the agent loads on demand. Use for workflows and bundled scripts.
* **[MCP configs](/api/mcp-configs/overview)** — external tool servers the agent can call. Use for live API access and integrations.