# skills — Manual

## What it does
The catalog of **skills** and **protocols** this Navi has been taught: reusable methodologies, stored per user or shared by the hive. `search` finds entries; `load` returns one in full.

- **skill** — knowledge about an approach: when it applies, heuristics, a private algorithm. Advice you follow as far as it fits.
- **protocol** — a strict ordered procedure: mandatory steps, a check after each, preconditions and post-checks, and three explicit escape hatches. Following it is a commitment.

Search before improvising a recurring task — one call often replaces several turns of rediscovery.

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `op` | yes | `search` \| `load`. |
| `query` | for `search` | Words matched against name, description, triggers and tags. |
| `kind` | no | `skill` \| `protocol` — filter, or disambiguate on `load`. |
| `tag` | no | Require this tag. |
| `area` | no | `home` \| `infrastructure` \| `workflows` \| `general`. |
| `id` | for `load` | Entry id from a search result. |
| `name` | for `load` | Exact name, when you have no id. |

## Actions

### `search`
```json
{"op": "search", "query": "энергосбережение", "area": "home"}
{"op": "search", "kind": "protocol", "tag": "power"}
```
Returns one line per entry: kind, name, version, area/visibility, description, tags, id. Personal entries come first.

### `load`
```json
{"op": "load", "id": "3f2a9c1d8e4b7a60"}
{"op": "load", "name": "Корректное выключение инфраструктуры", "kind": "protocol"}
```
For a skill, returns the instructions. For a protocol, returns the steps, the precondition list, the post-checks and the three escape hatches.

## When a protocol is loaded
Read the escape hatches before step 1. They are part of the procedure, not commentary:

- **off plan** (`on_deviation`) — what to do when reality differs from the plan;
- **cannot complete** (`on_blocked`) — how to stop cleanly and report;
- **already done** (`on_already_done`) — how to verify and skip a step whose result already exists.

Do not silently improvise around a step. A protocol exists because the user pre-agreed to the exact actions it names; deviating is an execution error to report, not a variation to choose.

## Format (for the catalog editor, not the tool)
A document is a YAML front matter block plus a markdown body:

```markdown
---
kind: protocol
name: Корректное выключение инфраструктуры
description: Останавливает сервисы в порядке зависимостей и проверяет, что диск не в работе.
area: infrastructure
tags: [power, shutdown]
triggers:
  - "пользователь просит выключить сервер"
  - "плановое отключение питания"
steps:
  - "Остановить сервисы приложений"
  - "Остановить базы данных"
  - "Синхронизировать и отмонтировать диски"
post_checks:
  - "systemctl list-units --state=running не содержит прикладных юнитов"
on_deviation: "Если шаг не удался — не продолжать, вернуться к предыдущему и доложить."
on_blocked: "Если сервис не останавливается за 60 с — остановить выключение и доложить."
on_already_done: "Проверить статус; если сервис уже остановлен — отметить шаг выполненным."
---

Дополнительный контекст, порядок зависимостей и известные ловушки.
```

`steps`, `post_checks`, `on_deviation`, `on_blocked`, `on_already_done` are **mandatory** for `kind: protocol`; a skill needs only `name` and a body.