Навыки (Skills): Agent Skills через MCP

Расширение io.modelcontextprotocol/skills позволяет серверу MCP отдавать клиенту навыки агента (Agent Skills) — папки с файлом SKILL.md и приложениями. Клиент находит навыки, читает их описание и загружает инструкции только тогда, когда задача их требует.

Что это#

Навык — каталог с файлом SKILL.md и необязательными файлами, по спецификации Agent Skills. Расширение не меняет формат навыка, а описывает, как найти и получить его по MCP: инструкции хранятся рядом с сервисом, который они описывают. Удобно для повторяемых сценариев, которые сочетают несколько инструментов или требуют справочных материалов, — проверка кода, обработка документов.

Само чтение SKILL.md через resources/read навык не включает. Хост пропускает чтение через свой путь загрузки навыков: проверяет содержимое и, если нужно, спрашивает согласие пользователя. Кто выбирает навык — модель по описанию или пользователь явно — решает хост; расширение этого не предписывает.

Объявление возможности#

Сервер, который поддерживает навыки, ОБЯЗАН объявить в ответе server/discover и возможность resources, и расширение io.modelcontextprotocol/skills:

{
  "capabilities": {
    "resources": {},
    "extensions": {
      "io.modelcontextprotocol/skills": {
        "directoryRead": true
      }
    }
  }
}

Объявив расширение, сервер ОБЯЗАН реализовать skills/list и skills/get; файлы навыков отдаются через resources/read. Необязательный флаг directoryRead (по умолчанию false) говорит, что сервер поддерживает resources/directory/read. Пустой объект расширения — поддержка без чтения каталогов. Клиент вызывает skills/list и skills/get только после того, как увидел объявление.

В примерах ниже для краткости опущены поля _meta; в настоящих запросах они обязательны (подробнее).

Список навыков#

Запрос skills/list поддерживает постраничную выдачу и кэширование:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "skills/list",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "skills": [
      {
        "uri": "skill://code-review/SKILL.md",
        "frontmatter": {
          "name": "code-review",
          "description": "Review code using the team's checklist."
        },
        "resources": [
          {
            "uri": "skill://code-review/SKILL.md",
            "digest": "sha256:d2489d6c182e8df9c178563ff9f2eac7998a0c1bb1278c52a7fd5306e4259160",
            "size": 149
          },
          {
            "uri": "skill://code-review/references/checklist.md",
            "digest": "sha256:dbab2de7bf7db9cc95cb6ce681c3690b26184db39f75b958a0287ca6d9e24e20",
            "size": 65
          }
        ]
      }
    ],
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

Поля записи#

Манифест ОБЯЗАН включать SKILL.md и каждый вспомогательный файл. Запись из skills/list полная: дозапрашивать её через skills/get не нужно. Если в ответе есть nextCursor, клиент передаёт его в params.cursor. Ответы ОБЯЗАНЫ содержать resultType: "complete", ttlMs и cacheScope — они описывают свежесть, а не целостность.

Навык определяется парой «сервер + адрес». Имена — только метки и могут совпадать. Серверам СЛЕДУЕТ использовать схему skill://, но МОЖНО и другую; хост НЕ ДОЛЖЕН считать ресурс навыком только по схеме адреса.

Один навык по адресу#

Запрос skills/get возвращает запись навыка в result.skill — той же формы, что в списке. Адрес может прийти от пользователя, другого навыка или из указаний сервера:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "skills/get",
  "params": {
    "uri": "skill://code-review/SKILL.md"
  }
}

Сервер МОЖЕТ отдавать пустой или неполный список, но ОБЯЗАН отвечать на skills/get для каждого навыка, который обслуживает. Хост ОБЯЗАН уметь загружать навык по адресу, даже если его нет в списке.

Чтение содержимого#

Инструкции и файлы читаются обычным resources/read:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/read",
  "params": {
    "uri": "skill://code-review/SKILL.md"
  }
}

В ответе — текст SKILL.md (mimeType: "text/markdown"). Файл ОБЯЗАН начинаться с YAML-заголовка с полями name и description, а последняя часть пути к его папке ОБЯЗАНА совпадать с name:

---
name: code-review
description: Review code using the team's checklist.
---

# Code review

Read `references/checklist.md`, then review the diff.

Относительные ссылки разрешаются от корня навыка: references/checklist.md превращается в skill://code-review/references/checklist.md и читается с того же сервера. Хост НЕ ДОЛЖЕН получать файлы заранее — при подключении, получении списка или согласии; согласие привязывается к манифесту, а не к скачанным файлам.

Чтение каталогов#

Метод resources/directory/read необязателен: клиент НЕ ДОЛЖЕН вызывать его без directoryRead: true. Он возвращает только прямых потомков каталога; адрес каталога пишется без завершающего слэша, вложенные каталоги помечены mimeType: "inode/directory". Живой список каталога НЕ расширяет сохранённый манифест: новые файлы становятся частью навыка только после обновления записи и, если нужно, нового согласия.

Проверка целостности#

Пока навык используется, хост хранит запись, по которой его загрузил. Для навыков с манифестом хост ОБЯЗАН:

1. читать только адреса из сохранённого манифеста;
2. перед использованием сверять размер и SHA-256 каждого файла;
3. разбирать YAML-заголовок SKILL.md и сравнивать его с frontmatter записи поле за полем.

Содержимое, не прошедшее проверку, использовать НЕЛЬЗЯ; устаревшую запись обновляют через skills/get. Сохранённое согласие привязано ко всему набору адресов и дайджестов: изменённый, добавленный или удалённый файл его отменяет.

Требования и ограничения#

• Сервер отдаёт корректные Agent Skills, сохраняет все поля заголовка и публикует полные манифесты, посчитанные по отдаваемым байтам (кроме "dynamic").
• Запись навыка атомарна: манифест НЕ ДОЛЖЕН разрываться между страницами списка.
• Серверу НЕ СЛЕДУЕТ превышать 512 файлов или 16 МиБ на навык; хост ОБЯЗАН поддерживать навыки до этих пределов.
• Навыки с "resources": "dynamic" хост МОЖЕТ отклонить; приняв, всё равно сверяет заголовок и не распространяет прежнее согласие на будущее содержимое.

Ошибки#

Общие коды — на странице «Ошибки».

Навыки сайта без MCP#

Помимо MCP, есть черновик Cloudflare Agent Skills Discovery: сайт публикует список навыков по адресу /.well-known/agent-skills/index.json. Это не часть MCP. Наличие такого файла, а также карточки MCP-сервера /.well-known/mcp/server-card.json, справочно показывает сканер agentreadyscan.ru. Что такое навыки агента простыми словами — на ии-навыки.рф, термин — в словаре Агентономики.