MCP HubMCP Hub
POST·BUILDY

Как создать свой первый плагин для агента: пошаговое руководство

AIMCP Teamon 19 days ago · 2 min read

Как создать свой первый плагин для агента: пошаговое руководство

Agent Plugins (v1.0.0) — это портативный стандарт упаковки компонентов агента (навыков и MCP-серверов), который работает во всех совместимых клиентах. В этом руководстве вы с нуля создадите реальный плагин, соответствующий спецификации: плагин, который включает один навык и один MCP-сервер, а затем проверите его по официальной схеме.

Шаг 1: Создайте структуру пакета

Плагин — это просто директория. Создайте её с двумя обязательными элементами:

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       └── SKILL.md
└── mcp.json

Шаг 2: Напишите манифест

plugin.json — единственный обязательный файл. Схема манифеста закрытая — портативные поля верхнего уровня ограничены фиксированным набором:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "summarize.tools",
  "version": "1.0.0",
  "description": "Навыки и серверы для суммаризации документов.",
  "author": {
    "name": "Ваше Имя",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/summarize-tools",
  "repository": "https://github.com/you/summarize-tools",
  "license": "MIT",
  "keywords": ["summarization", "documents", "llm"]
}

Только $schema и name обязательны. Всё остальное опционально, но рекомендуется: version (SemVer), description, author, homepage, repository, license (SPDX) и keywords для поиска.

Примечание: схема закрыта по замыслу. Настройки для конкретных клиентов должны находиться в пространствах имён расширений, а не в полях верхнего уровня.

Шаг 3: Добавьте навык

Навыки находятся в skills/ и следуют спецификации Agent Skills. Каждая дочерняя директория первого уровня, содержащая файл SKILL.md, считается одним навыком:

skills/
└── summarize/
    ├── SKILL.md
    ├── scripts/
    │   └── summarize.py
    └── references/
        └── guidelines.md

Минимальный SKILL.md:

---
name: summarize
description: Суммаризируйте документ, выделяя ключевые моменты. Используйте, когда пользователь просит сократить длинный текст.
---

# Summarize

1. Прочитайте документ из ввода пользователя.
2. Извлеките основной тезис, поддерживающие аргументы и пункты для действий.
3. Напишите итог в формате markdown, максимум 10 пунктов списка.

## Скрипты

- `scripts/summarize.py` — CLI-инструмент, который принимает путь к файлу и выводит итог.

Клиенты обнаруживают навыки, сканируя skills/*/SKILL.md; они не углубляются дальше, поэтому размещайте по одному навыку в каждой дочерней директории первого уровня.

Шаг 4: Добавьте MCP-сервер

Если ваш плагин включает MCP-сервер, опишите его в mcp.json. Формат поддерживает транспорты stdio, Streamable HTTP и устаревший HTTP+SSE:

{
  "servers": {
    "summarize": {
      "command": "python",
      "args": ["scripts/mcp_server.py"],
      "env": {}
    }
  }
}

Клиенты преобразуют этот портативный формат в свою родную конфигурацию — имена полей не обязаны совпадать с внутренним форматом любого клиента.

Шаг 5: (Опционально) Добавьте клиентские расширения

Хотите добавить поведение для конкретного клиента, не форкая основную часть? Используйте директорию пространства имён в формате обратного домена, названную в честь вашего клиента, например, com.example.client/hooks/hooks.json. Клиенты ищут свою директорию пространства имён в корне плагина; неизвестные пространства имён игнорируются.

Шаг 6: Проверка

Перед распространением проверьте свой манифест:

  1. $schema должна ссылаться на официальный URL схемы: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json.
  2. name должен присутствовать и быть непустым — отсутствие обязательного поля делает весь плагин недействительным, и клиенты должны его отвергнуть.
  3. Убедитесь, что фронтмэттер вашего SKILL.md содержит как минимум name и description.
  4. Проверьте mcp.json по JSON-схеме спецификации (опубликована на agent-plugins.org/schemas).

Вы также можете использовать пример плагина из репозитория спецификации (agentplugins/agent-plugins-example) в качестве канонического образца или прогнать свой плагин через отправку в каталог AIMCP — он проверяется по официальной схеме и сообщает количество компонентов.

Шаг 7: Распространение

Плагин для агента — это директория, поэтому распространение гибкое: загрузите его в репозиторий GitHub, опубликуйте в маркетплейсе или поделитесь напрямую. Совместимые клиенты обнаруживают и загружают плагины единообразно, независимо от способа доставки.

Дальнейшие шаги