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

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

Чтобы использовать навыки агента в разных репозиториях, прекратите копировать файлы и начните использовать их как зависимости. Создайте один репозиторий для навыков, присваивайте ему теги и позвольте каждому проекту фиксировать конкретную версию (тег). Затем добавьте 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 году

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

Файлы блокировок (Lockfiles). Инструмент командной строки 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, которая переустанавливает все отслеживаемые навыки из файла блокировки, чтобы на второй машине был развёрнут идентичный набор. Рассматривайте этот запрос как отчёт о текущем состоянии разработки. Концепция файла блокировки принята, но реализация привязки к конкретному проекту всё ещё находится в процессе создания.

Спецификации и тесты. SkillSpec подходит к вопросу с другой стороны. Он рассматривает SKILL.md как контракт для проверки, а не как текст, которому нужно доверять. Заявленная цель — сделать навыки «отслеживаемыми, тестируемыми и доказуемыми». skillspec doctor <path> сообщает, в каком месте агент с наибольшей вероятностью прервёт выполнение. skillspec boundary map <path> показывает, к чему навык может получить доступ, а skillspec boundary assess <path> ранжирует эти результаты по уровню риска. Это Rust-библиотека (crate) с двойной лицензией 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 перед тем, как принять обновление.

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

Структура репозитория для небольшой команды на собственном 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 или «голый» репозиторий по 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. Символ + в начале означает, что текущий извлеченный коммит отличается от зафиксированного, а значит, разработчик использует инструкции, которых нет у остальных. Новым клонам требуется git clone --recurse-submodules, и эту строку следует добавить в README, так как обычный clone оставляет 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
  }
}

Участнику команды, который доверяет папке проекта, будет предложено установить маркетплейс, и плагин будет включен для него автоматически, без необходимости изучать инструкции в wiki. Навыки затем будут доступны по адресу /team-skills:api-review, так как навыки плагинов имеют пространство имен, соответствующее названию плагина, и не могут конфликтовать с навыком проекта с тем же именем. После того как вы отправите (push) новый тег, потребители обновляют данные с помощью /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 может выполнять команды оболочки до того, как модель что-либо прочитает. Строка подобного вида в теле файла является предварительной обработкой:

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

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

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

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

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

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

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

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

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

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

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

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

FAQ

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

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

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

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

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

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

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

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

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

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