Overview

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

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

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.

---
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 for the strict validation rules (size limits, name format, etc.).

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 (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

• 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

• Rules — 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 — external tool servers the agent can call. Use for live API access and integrations.