---
title: "06 — Skills"
description: "## What a skill is"
section: ai-docs
raw: "06-skills.md"
source: ai-generated
tags: ai, llama.cpp, docker
last-updated: 2026-09-15
---

# 06 — Skills

> Skills: packaged, reusable units of knowledge/procedure that an agent loads on demand to do a specific job well — and how to build and manage them.

## What a skill is

A **skill** is a self-contained bundle that teaches an agent *how to do a particular kind of task*. Where a model's weights carry general knowledge and the system prompt carries standing instructions, a skill carries **domain-specific procedure plus reference material** for a narrow job. It's the difference between "the model knows about git" and "the model knows *this repo's* git conventions and will run `markdownlint` after editing."

A skill typically combines:

- **A trigger / description** — when the agent should reach for this skill (matched from the user's request).
- **Procedure** — the steps, in order, to accomplish the task.
- **Reference material** — file locations, templates, commands, conventions, gotchas.
- **Boundaries** — what the skill is *not* for, and guardrails (e.g. "never commit secrets", "get confirmation before X").

## Why skills exist (the context problem)

An agent can't load everything it might ever need into context — that's both expensive and degrading (see [Context Sizing](/ai-docs/02-context-and-quantisation/)). Skills solve this with **on-demand, just-in-time knowledge**: the description list is cheap to keep resident, and the full skill body is loaded only when the task matches. This is the same isolation principle as [sub-agents](/ai-docs/04-sub-agents/), but applied to *knowledge* rather than *work*:

- **Sub-agent** = delegate *execution* to a fresh context.
- **Skill** = inject the right *knowledge* into the context for this task.

They compose naturally: a sub-agent prompt that references the relevant skill gives the worker both a clean context *and* the domain procedure it needs.

## Anatomy of a good skill

A skill that an agent actually uses well has a few properties:

- **One skill per job.** "NANDA Docs", "deploy a llama server", "rotate a Postgres secret" — not a catch-all. A broad skill is one the agent can't reliably trigger.
- **Self-contained.** Everything needed to do the job is in the skill: absolute paths, exact commands, template locations, the conventions. The agent shouldn't have to guess or ask.
- **Prescriptive, not descriptive.** Give the exact command and the exact file, not "run the linter somewhere".
- **Guardrails up front.** Safety constraints (redact secrets, confirm before committing, don't hard-wrap prose) belong in the skill so they apply every time the skill is used.
- **Stable, small, and versionable.** Skills live in the agent's workspace (often as files in a known directory) and are reviewed like code. When a procedure changes, the skill changes.

## Skills vs the things they're confused with

| Thing | What it is | Relation to a skill |
| --- | --- | --- |
| **System prompt** | Standing, always-loaded instructions | A skill is *loaded on demand*; the system prompt is resident. Put cross-cutting rules in the system prompt; task-specific procedure in a skill. |
| **Tool** (e.g. Open Terminal) | A *capability* — something the agent can *do* | A skill is *knowledge* about how to use capabilities well. A skill frequently *references* tools (e.g. "run `markdownlint-cli2` via the terminal"). |
| **Sub-agent** | A delegated *execution* in a fresh context | A skill can be handed to a sub-agent as its brief; the sub-agent provides the clean context, the skill provides the procedure. |
| **MCP server** | A protocol for exposing tools/data | MCP is *how* tools are wired in; a skill is *what to do* with them. |

The clean way to think about it: **tools are hands, skills are the manual, sub-agents are the fresh pair of hands.**

## How an agent uses a skill (the loop)

```text
User request
   │  agent scans available skill *descriptions* (cheap, resident)
   ▼
Match?  ──no──► proceed without a skill
   │yes
   ▼
Load the skill *body* into context (procedure + references + guardrails)
   │
   ▼
Follow the procedure, calling tools (terminal, file ops, …) as needed
   │  may delegate a step to a sub-agent, passing the skill as its brief
   ▼
Done — result returned; skill body can be dropped from context
```

Because only the *description* list needs to be resident, you can have many skills without paying for their full bodies until one is actually used.

## Tips for building skills on a local stack

- **Start from a real task.** Do the job once by hand, note every command, path, and decision, and codify that. A skill distilled from a real run is far more reliable than one written abstractly.
- **Use absolute paths.** A skill that says "the repo is at `/home/u/…/NANDA` and the template is at `templates/doc.md`" removes an entire class of "which file?" failures.
- **Keep guardrails in the skill, not in your head.** If you've ever had to remind the model "redact secrets before committing", that reminder belongs in the skill so it fires automatically.
- **Version skills like code.** Put them in a git-backed directory, review changes, and keep them current when the underlying procedure changes — a stale skill is worse than no skill, because the agent trusts it.
- **Match skill granularity to model.** A small worker model benefits most from a *very* prescriptive skill (exact commands, no judgement); a large model can work from a looser brief. Pair skill detail with the model that will execute it (see [Sub-agents](/ai-docs/04-sub-agents/)).

## Related

- [Sub-agents](/ai-docs/04-sub-agents/) — skills as sub-agent briefs
- [Open Terminal & Tooling](/ai-docs/05-open-terminal-and-tooling/) — the tools skills direct
- [Context & Quantisation](/ai-docs/02-context-and-quantisation/) — the context economics that motivate on-demand loading

---

## Source Disclaimer

- [x] AI Generated
- [ ] Human Generated
- [ ] AI Edited
- [ ] Human Edited