SSD Nodes Learn Hosting plans →
Руководства Matt ConnorАвтор: Matt Connor · Обновлено 2026-08-26

Как использовать навыки агента в разных репозиториях

Копирование навыков агента приводит к рассинхронизации кода. Используйте подход с зависимостями: вынесите навыки в отдельный репозиторий и фиксируйте версии в каждом проекте.

Как использовать навыки агента в разных репозиториях

Чтобы использовать навыки агента в разных репозиториях, прекратите копировать файлы и начните использовать зависимости. Создайте один репозиторий для навыков, присвойте ему тег и позвольте каждому проекту зафиксировать этот тег. Затем добавьте smoke-тест для каждого навыка и проверяйте каждое обновление версии так же, как вы проверяете обновление зависимостей.

Это состоит из четырех частей: единый источник истины, зафиксированная версия для каждого репозитория, smoke-тест для каждого навыка и процесс проверки изменений. Ниже объясняется, зачем нужна каждая часть, что делают инструменты, которые выходят в 2026 году, и как построить всю систему на собственном git-сервере без использования сторонних сервисов.

Навык агента — это папка, содержащая файл SKILL.md, а также все необходимые скрипты и справочные файлы. Если этот модуль для вас в новинку, сначала прочитайте что такое навык агента и как работает SKILL.md. Эта страница посвящена цепочке поставок вокруг данного модуля.

Где хранятся навыки и почему их сложно распространять

Claude Code загружает навыки из трех источников, каждый из которых указан в документации по навыкам.

  • ~/.claude/skills/<skill-name>/SKILL.md — персональный уровень. Навыки загружаются во всех ваших проектах и недоступны другим пользователям.
  • .claude/skills/<skill-name>/SKILL.md — уровень проекта. Навыки загружаются для любого пользователя, который клонирует этот репозиторий.
  • <plugin>/skills/<skill-name>/SKILL.md — уровень плагина. Навыки загружаются везде, где активирован соответствующий плагин.

Средний вариант наиболее полезен для команды, так как он фиксируется в системе контроля версий и становится доступен всем, кто клонирует репозиторий. Именно здесь возникают сложности. Навык в .claude/skills/ привязан к одному репозиторию. Если у вас восемь репозиториев, навык приходится копировать восемь раз.

Заголовок (frontmatter) не решает эту проблему. Спецификация Agent Skills допускает использование шести ключей, а пути распространения, которые обеспечивают соблюдение этого правила, выводят список доступных ключей при попытке использовать недопустимый:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Обратите внимание на отсутствие ключа version. Внутри файла нет записи о том, какая копия является более новой. Это логично, так как навык представляет собой документ, а не пакет. Однако это означает, что управление версиями должно осуществляться на уровне, внешнем по отношению к файлу, и эта задача ложится на вас.

Проблема первая: восемь копий, которые незаметно расходятся

Копирование и вставка работают в первый день. Они перестают работать на шестидесятый. Кто-то исправляет неверную инструкцию в репозитории payments и не вносит изменения в остальные семь. Кто-то другой добавляет правило о пагинации в orders. Теперь одно и то же имя навыка выдает два разных результата в зависимости от того, из какой директории был запущен агент, и ни один из разработчиков об этом не знает.

Сбой происходит незаметно, так как отсутствует состояние ошибки. Навык — это текст. Устаревшая инструкция порождает уверенный, но неверный ответ, что является наиболее затратным вариантом. В агенте нет механизма, который сравнивал бы вашу копию с остальными, поэтому единственным сигналом служит момент, когда человек замечает расхождение между двумя репозиториями.

Проблема вторая: отсутствие фиксации версий

Даже если команда хранит навыки в одном месте, стандартным методом обмена является копирование: скрипт настройки, строка curl в документации для новых сотрудников или shell-алиас, синхронизирующий папку. Все эти способы устанавливают то, что находится в текущей версии ветки на данный момент.

Это означает, что два разработчика, работающие с одним и тем же коммитом одного приложения, могут использовать разные инструкции, так как они выполнили синхронизацию в разные дни. Это также означает, что вы не сможете ответить на важный вопрос после неудачного запуска агента: какая версия навыка это вызвала? Без зафиксированной ревизии запуск невозможно воспроизвести, поэтому отчет об ошибке нельзя взять в работу.

Проблема третья: никто не знает, работает ли навык до сих пор

У навыка нет компилятора. Это набор инструкций для модели, поэтому он может перестать работать, даже если файл остался побайтово идентичным. Обновление модели меняет степень точности выполнения длинных инструкций. Инструмент командной строки, который вызывает навык, может переименовать флаг. URL в справочном файле начинает возвращать 404, и агент начинает работать на основе страницы ошибки.

Ни в одном из этих случаев не происходит явного сбоя. Агент продолжает отвечать. Просто ответ стал хуже, чем был в прошлом месяце, а это сложно заметить, если проверять изменения по одному pull request за раз.

Что решают инструменты, выходящие в 2026 году

Сейчас появляется несколько решений, и их авторы расходятся во мнениях о том, где именно должна храниться версия.

Lock-файлы. Инструмент командной строки skills от Vercel Labs (vercel-labs/skills, лицензия MIT, версия 1.5.22 на 5 августа 2026 года) устанавливает навыки (skills) из git-репозитория в директорию, которую ожидает ваш агент; инструмент поддерживает структуру более семидесяти агентов. npx skills add <repo> выполняет установку, npx skills update — обновление, а npx skills list показывает текущий список. Запись об установленных компонентах ведётся один раз на пользователя, а не на репозиторий. В этом проекте открыт запрос (issue 283) на добавление команды skills install, которая переустанавливает все отслеживаемые навыки из lock-файла, чтобы на второй машине был идентичный набор. Рассматривайте этот запрос как отчёт о текущем статусе. Идея с lock-файлами принята, но реализация привязки к конкретному проекту всё ещё находится в разработке.

Спецификации и тесты. SkillSpec подходит к вопросу с другой стороны. Он рассматривает SKILL.md как контракт, который нужно проверять, а не как текст, которому нужно доверять. Заявленная цель — сделать навыки «отслеживаемыми, тестируемыми и доказуемыми». skillspec doctor <path> сообщает, в каком месте агент с наибольшей вероятностью прервёт выполнение. skillspec boundary map <path> показывает, к чему навык может получить доступ, а skillspec boundary assess <path> ранжирует эти результаты по уровню риска. Это Rust-библиотека с двойной лицензией MIT или Apache 2.0, версия 0.2.2 на 29 июля 2026 года. Устанавливайте зафиксированную версию, а не самую новую:

cargo install skillspec --version 0.2.2 --locked
skillspec --version

--locked выполняет сборку с теми версиями зависимостей, с которыми библиотека была опубликована, поэтому сборка не будет меняться без вашего ведома. skillspec --version должен вывести 0.2.2. Другое число означает, что в вашем PATH приоритет имеет более старый бинарный файл.

Практика вендоринга. Google описала процесс сборки навыков в google/skills в статье о том, как компания собирает, тестирует и масштабирует навыки агентов. Если отбросить масштаб, то механизм представляет собой обычную непрерывную интеграцию (CI). Каждый навык перед слиянием проходит линтеры метаданных frontmatter, количества строк, структуры директорий и именования. Проверка ссылок прерывает сборку при обнаружении любого URL, возвращающего 404, что позволяет выявить правдоподобные ссылки, выдуманные агентом. Авторы обязаны предоставлять набор оценочных промптов и критерии оценки вместе с самим навыком. Регулярные задания по оценке запускаются еженедельно для всей библиотеки, чтобы выявлять регрессии, а у каждого навыка есть ответственный владелец, который должен исправлять ошибки при снижении качества.

Общая закономерность для всех трех ответов

Вам не обязательно выбирать что-то одно. В основе всех этих подходов лежит единая структура, и стандартный git предоставляет все необходимые инструменты для её реализации.

  1. Единый источник истины. У навыка есть только одно место хранения, и каждый репозиторий ссылается на него, вместо того чтобы хранить собственную копию.
  2. Фиксированная версия для каждого репозитория. Каждый проект записывает точную ревизию, которую он использует, поэтому обновление представляет собой коммит в этом проекте с указанием автора и даты.
  3. Дымовое тестирование для каждого навыка. Одна запускаемая проверка, подтверждающая, что навык по-прежнему выдает ожидаемый результат.
  4. Путь прохождения проверки. Изменения в общем навыке проходят через процедуру ревью, и каждый потребитель видит diff перед тем, как принять обновление.

Такова структура зависимости. Навыки стали общими артефактами быстрее, чем вокруг них сформировался инструментарий, поэтому использование инструментов, которым вы уже доверяете, — самый безопасный путь.

Структура репозитория для небольшой команды на self-hosted git-сервере

В одном репозитории хранятся навыки и инструкции. В нем нет ничего другого, поэтому его история выглядит как журнал изменений с описанием действий.

agent-skills/
  skills/
    api-review/
      SKILL.md
    release-notes/
      SKILL.md
  tests/
    api-review.sh
    release-notes.sh
  CHANGELOG.md

Релизы оформляются через теги. Используйте аннотированные теги, так как они содержат сообщение и дату. В сообщении указывайте причину, по которой потребителю стоит обновить версию:

git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0

Если ваш удаленный сервер — это Gitea, Forgejo, GitLab или просто bare-репозиторий по SSH на вашем VPS, ничего из описанного ниже не меняется. Все здесь — это git плюс символическая ссылка.

Фиксация версии через git submodule

Подмодуль (submodule) сохраняет конкретный коммит другого репозитория внутри вашего репозитория. Эта запись и является фиксацией (pin). В каждом использующем проекте:

git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"

Символическая ссылка — это механизм, который обеспечивает работу данной схемы. Запись о навыке (skill) на уровне проекта может быть ссылкой на директорию в другом месте диска, и Claude Code переходит по ней, считывая SKILL.md из целевой папки. Таким образом, навык загружается как обычный проектный навык, в то время как сами данные находятся в подмодуле на выбранном вами коммите.

Проверьте фиксацию:

git submodule status

Корректная строка начинается с пробела, затем следует коммит, путь и ближайший тег:

 4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)

Наличие - в начале строки означает, что подмодуль не был инициализирован, поэтому .claude/skills/api-review указывает в никуда, и навык молча не загружается. Исправьте это с помощью git submodule update --init. Наличие + означает, что текущий проверенный (checked-out) коммит отличается от зафиксированного, а значит, разработчик использует инструкции, которых нет у остальных. Новым клонам требуется git clone --recurse-submodules, и эту строку следует добавить в README, так как обычный клон оставляет vendor/agent-skills пустым и не выводит ошибок.

Обновление выполняется осознанно, в этом и заключается основной смысл:

git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"

Строка diff — это путь для проверки изменений. Она показывает те же изменения, которые увидят все остальные использующие репозитории, и её удобно включать в pull request.

Использование маркетплейса плагинов для фиксации версий

Если вы не хотите заставлять каждого разработчика изучать работу с подмодулями, система плагинов Claude Code возьмет распространение на себя, работая с вашим собственным удаленным репозиторием. Разместите каталог по пути .claude-plugin/marketplace.json в репозитории навыков:

{
  "name": "acme-agents",
  "owner": { "name": "Platform team", "email": "platform@example.com" },
  "plugins": [
    {
      "name": "team-skills",
      "description": "Shared review and release skills",
      "version": "1.4.0",
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0",
        "sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
      }
    }
  ]
}

Здесь задействованы два разных источника, и их путаница — распространенная ошибка. Источник маркетплейса, то есть место, откуда загружается сам каталог, принимает ref для ветки или тега и не принимает sha. Источник плагина внутри каталога принимает оба варианта, и если заданы оба, то sha является приоритетным для фиксации версии. Таким образом, фиксация конкретного коммита должна быть указана в записи каталога.

Каждый использующий репозиторий затем объявляет маркетплейс в своем зафиксированном файле .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "acme-agents": {
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0"
      }
    }
  },
  "enabledPlugins": {
    "team-skills@acme-agents": true
  }
}

Члену команды, который доверяет папке проекта, будет предложено установить маркетплейс, и плагин будет включен для него автоматически, без необходимости изучать вики-страницу с инструкциями. Навыки затем будут доступны по команде /team-skills:api-review, так как навыки плагинов имеют пространство имен, соответствующее названию плагина, и не могут конфликтовать с навыками проекта с тем же именем. После того как вы отправите новый тег, потребители обновляются с помощью /plugin marketplace update acme-agents, а затем выполняют /reload-plugins, если этого требует сводка установки.

Написание smoke-теста для одного навыка

Smoke-тест — это автоматизированный запуск агента против фикстуры с известной ошибкой и одной проверкой (assertion). Claude Code выполняется в неинтерактивном режиме с помощью -p, и пользовательский навык работает в этом окружении: добавьте /skill-name в строку промпта, и она будет раскрыта перед началом выполнения.

#!/usr/bin/env bash
set -euo pipefail

claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --allowedTools "Read" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
  | jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/null

fixtures/orders-api.md — это небольшой файл с одной преднамеренной ошибкой. Проверка заключается в том, что навык должен идентифицировать эту ошибку. jq -e завершается с ненулевым кодом, если фильтр обнаруживает null, поэтому навык, который перестает находить внедренную ошибку, приводит к провалу скрипта. claude сам по себе завершается с ненулевым кодом при сбое запуска, а set -euo pipefail превращает любой из этих сбоев в проваленный тест.

Модель перефразирует свои ответы между запусками, поэтому никогда не делайте проверку по целому предложению. Выполняйте проверку по идентификатору, который должен выдать навык, или по полю схемы, которую вы запросили. Держите фикстуру небольшой, чтобы запуск оставался дешевым.

В CI добавьте --bare. Без него claude -p загружает тот же контекст, что и интерактивная сессия, включая хуки, плагины и CLAUDE.md с машины, на которой он запущен, поэтому персональная конфигурация коллеги может изменить результат. Bare mode пропускает все автообнаружения, что означает, что он также пропускает навык, который вы тестируете, поэтому загружайте его явно. Bare mode также не считывает ваши данные подписки, поэтому сначала установите ANTHROPIC_API_KEY в окружении:

claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --plugin-dir vendor/agent-skills \
  --allowedTools "Read" \
  --output-format json

С помощью --output-format stream-json первое событие запуска сообщает, какие плагины были загружены, и содержит массив plugin_errors для тех, которые не загрузились. Завершайте CI-задачу с ошибкой, если массив plugin_errors не пуст. Это позволяет обнаружить привязку к ревизии, которая больше не существует, что в противном случае выглядело бы как агент, молча игнорирующий ваши внутренние правила.

Общий навык — это исполняемая инструкция

Две функции делают это утверждение буквальным, и обе важны, когда файл поступает от другой команды.

Во-первых, SKILL.md может выполнять shell-команды до того, как модель прочитает что-либо. Строка подобного вида в теле файла является препроцессингом:

- Current branch: !`git rev-parse --abbrev-ref HEAD`

Команда выполняется на машине, загружающей навык, а её вывод заменяет плейсхолдер в тексте, который получает модель. Блок, открытый тремя обратными апострофами с последующим !, выполняет несколько команд таким же образом. Никто не подтверждает эти действия во время выполнения. Чтение общего навыка означает чтение его подстановок команд.

Во-вторых, frontmatter позволяет заранее одобрять инструменты. allowed-tools предоставляет доступ к перечисленным инструментам без запроса разрешения для сессии, в которой был вызван навык. Для проектного навыка это разрешение вступает в силу, как только пользователь принимает диалог доверия к рабочей области для данной папки. Документация Claude Code прямо указывает на последствия: проверяйте проектные навыки перед тем, как доверять репозиторию, поскольку навык может самостоятельно предоставить себе широкие права доступа к инструментам.

Поэтому относитесь к обновлению навыка точно так же, как к обновлению зависимостей. Фиксируйте версию по точному commit везде, где это позволяет механизм, поскольку тег может быть перемещен, а ветка меняется по определению. На защищенной машине параметр "disableSkillShellExecution": true в настройках заменяет любую подстановку команд на литеральный текст [shell command execution disabled by policy] вместо их выполнения; при применении через управляемые настройки пользователь не может это переопределить. Встроенные и управляемые навыки исключаются из действия этой настройки.

Такая же осторожность требуется в отношении того, что навык считывает. Навык, который запускает env или открывает конфигурационный файл, подтягивает всё найденное в контекст модели, что является ошибкой, описанной в защите секретов от используемых агентов. Навык, который загружает страницу или выполняет запрос, представляет собой ту же угрозу, направленную вовне, поскольку полученный текст попадает в контекст, выглядя точно так же, как инструкции, которые вы написали. Это граница, о которой стоит прочитать, прежде чем вы направите агента на собственный экземпляр SearXNG для веб-поиска.

Что изучить при обновлении версии

  • Diff каждого тела SKILL.md, так как этот текст содержит инструкции, которым будет следовать ваш агент.
  • Любую подстановку команд, поскольку они выполняются на вашей машине при загрузке навыка.
  • Любые изменения в allowed-tools, так как эта строка предоставляет инструменты без дополнительного запроса.
  • Результаты тестового запуска, стоящего за тегом. Если в общем репозитории выполняются собственные smoke-тесты в CI, то тег, на который вы ссылаетесь, должен иметь статус успешного прохождения.

Если рецензент не может изучить весь diff за десять минут, значит, навык стал слишком объёмным. Разделите его. Тот же аргумент применим к документации репозитория, которую читают ваши агенты: храните постоянные правила в файлах, описанных в разделении AGENTS.md и HUMAN.md, а архитектурные обоснования — в DESIGN.md, написанном для агентов, и пусть навыки остаются узкоспециализированными процедурами.

Когда изменение модели или инструмента нарушает работу навыка

Под навыком могут происходить изменения, даже если никто не вносил в него правок. Обновление модели меняет надежность выполнения длинных инструкций: навык, который раньше доходил до девятого шага, может перестать это делать. Инструмент командной строки переименовывает флаг, агент запускает старый флаг, получает ошибку и начинает импровизировать. Ссылаемый URL начинает возвращать 404. Механизм выбора навыков в агенте меняется, и description, который раньше выигрывал, больше не выбирается. Когда процедура начинает завершаться раньше времени, обновление версии не помогает — сами инструкции требуют структуры, принудительно выполняющей последние шаги. Именно на этом подходе основан неленивый навык и его метод Depth Tree.

Поэтому в данной архитектуре критически важны smoke-тесты. Запускайте тест каждого навыка по расписанию и при каждом push. Google по этой причине еженедельно прогоняет оценочные задания по всей библиотеке, а для команды с десятью навыками достаточно еженедельного cron-задания на небольшом VPS. Это единственный способ узнать о поломке раньше разработчика.

Портативность также помогает. Спецификация Agent Skills ограничивает frontmatter шестью ключами. Навык, написанный по этой спецификации, загружается в инструментах, отличных от тех, для которых он создавался, в то время как каждый специфичный для конкретного механизма ключ — это ставка на одного вендора. Написание навыков, которые переживают смену модели, — это отдельная дисциплина, описанная в обеспечении работы навыка на любой модели.

FAQ

Как использовать один навык агента в нескольких репозиториях?

Разместите навык в отдельном git-репозитории, создавайте в нем релизы с тегами и настройте каждый проект-потребитель на использование конкретного тега вместо копирования файла. Существует два способа. Git-подмодуль фиксирует конкретный коммит, а символическая ссылка из .claude/skills/<name> в подмодуль позволяет загрузить его как обычный навык проекта. Маркетплейс плагинов выполняет ту же задачу через /plugin, где привязка к версии указывается в .claude/settings.json репозитория-потребителя. Оба метода сохраняют версию в истории git, что позволяет отследить, какие именно инструкции использовались при конкретном запуске агента.

Можно ли закрепить навык агента за конкретной версией?

Это невозможно сделать внутри SKILL.md, так как в этом заголовке отсутствует ключ version. Привязка должна осуществляться на уровне, внешнем по отношению к файлу. Git-подмодуль по своей архитектуре фиксирует конкретный коммит. В маркетплейсе плагинов Claude Code источник плагина поддерживает ref для ветки или тега и sha для конкретного коммита, при этом sha имеет приоритет, если указаны оба параметра. Сам источник маркетплейса поддерживает только ref. Рекомендуется использовать привязку к коммиту, так как тег может быть изменен после того, как вы его проверили.

Что должен проверять smoke-тест навыка?

Проверяйте стабильные показатели. Запустите навык в неинтерактивном режиме на фикстуре, содержащей известную ошибку, а затем убедитесь, что в выводе присутствует конкретный идентификатор, например, ID правила, которое навык должен обнаружить. Запрос структурированного вывода с помощью --output-format json и --json-schema делает проверку точной, а jq -e завершает скрипт с ошибкой, если значение отсутствует. Никогда не проверяйте полное предложение, так как модель может перефразировать ответы при разных запусках.

Безопасно ли устанавливать общий навык из репозитория другой команды?

Относитесь к этому как к зависимости в коде, поскольку это исполняемая инструкция. SKILL.md может выполнять shell-команды во время загрузки через подстановку команд !, а поле allowed-tools в заголовке может заранее разрешать использование инструментов без запроса подтверждения. Просматривайте diff при каждом обновлении, привязывайтесь к конкретному коммиту, а не к ветке, и отдавайте предпочтение источникам, которые контролирует ваша команда. На управляемых машинах параметр "disableSkillShellExecution": true в настройках полностью отключает выполнение подстановок команд.

Будет ли общий навык работать в других агентах, помимо Claude Code?

Это зависит от того, какие поля заголовка вы используете. Спецификация Agent Skills определяет шесть ключей: name, description, license, compatibility, metadata и allowed-tools. Навык, ограниченный этими ключами, загружается во всех инструментах, реализующих спецификацию, и без изменений работает в Claude Code. Специфичные для конкретной среды ключи и функции тела навыка, выходящие за рамки спецификации, будут проигнорированы или отклонены другими инструментами, поэтому не используйте их в навыках, предназначенных для широкого распространения.

#agent-skills#versioning#claude-code#team-standards#self-hosting