SSD Nodes Learn 🎉 VPS від $5.50/міс
Посібники Matt ConnorВід Matt Connor · Оновлено 2026-08-13

Як ділитися skills між репозиторіями без розбіжностей

Копії skills у восьми репозиторіях з часом розходяться. Зберігайте їх в одному репозиторії, додавайте версії тегами та фіксуйте тег у кожному проєкті.

Як спільно використовувати навички агента в різних репозиторіях

Щоб використовувати навички агента в різних репозиторіях, не копіюйте файл, а зробіть залежність від нього. Створіть один репозиторій навичок, додайте до нього тег і дозвольте кожному проєкту зафіксувати потрібний тег. Потім додайте smoke test для кожної навички та перевіряйте кожне оновлення так само, як оновлення залежності.

Це складається з чотирьох частин: спільного джерела істини, зафіксованої версії для кожного репозиторію, smoke test для кожної навички та процесу перевірки. Нижче пояснюється, навіщо потрібна кожна частина, як інструменти, що випускаються у 2026 році, працюють із цим завданням і як побудувати всю систему на self-hosted git remote без використання зовнішніх сервісів.

Навичка агента — це папка, що містить файл SKILL.md, а також потрібні їй скрипти й довідкові файли. Якщо цей компонент для вас новий, спочатку прочитайте що таке навичка агента і як працює SKILL.md. Ця сторінка присвячена ланцюжку постачання для цього компонента.

Де розміщується skill і чому ним складно ділитися

Claude Code завантажує skills із трьох місць, перелічених у документації зі skills.

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

Для команди найкорисніший другий варіант, оскільки файл додається до репозиторію, і кожен, хто клонує репозиторій, отримує його. Тут же починаються проблеми. Skill у .claude/skills/ належить одному репозиторію. У вас є вісім репозиторіїв. Тому skill доводиться копіювати вісім разів.

Frontmatter не допомагає. Специфікація Agent Skills дозволяє шість ключів, а інструменти розповсюдження, які забезпечують цю вимогу, виводять цей список, якщо використати інший ключ:

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

Зверніть увагу, чого в ньому немає: ключа version не існує. Файл не містить жодних даних про те, яка копія новіша. Це логічно, оскільки skill є документом, а не пакетом. Однак версіювання має надходити з рівня навколо файлу, і цим рівнем потрібно керувати вам.

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

Копіювання працює в перший день. На шістдесятий день воно вже дає збій. Хтось виправляє неправильну інструкцію в репозиторії payments, але не змінює інші сім копій. Хтось інший додає правило щодо пагінації в orders. Тепер однакова назва skill дає два різні результати перевірки залежно від того, з якого каталогу запустився агент, і жоден із розробників цього не знає.

Збій залишається непомітним, оскільки стану помилки немає. Skill — це текст. Застаріла інструкція призводить до впевненої, але неправильної відповіді, а саме такі помилки коштують найдорожче. Агент не порівнює вашу копію з копіями в інших репозиторіях, тому єдиний сигнал — коли людина помічає, що два репозиторії не узгоджуються.

Проблема 2: версія ніде не фіксується

Навіть коли команда зберігає навички в одному місці, зазвичай їх поширюють копіюванням: setup-скриптом, рядком curl у документі для адаптації нових працівників або shell-аліасом, який синхронізує каталог. Усі ці способи встановлюють поточний стан гілки.

Через це два розробники можуть працювати з різними інструкціями, навіть якщо використовують той самий commit тієї самої програми. Причина в тому, що вони запускали синхронізацію в різні дні. Після невдалого запуску агента також неможливо відповісти на важливе запитання: яка версія навички це спричинила? Без записаної ревізії запуск неможливо відтворити, тому звіт про помилку не дає змоги розпочати діагностику.

Проблема 3: ніхто не знає, чи навичка досі працює

Навичка не має компілятора. Це інструкції для моделі, тому вона може перестати працювати, навіть якщо файл залишається повністю ідентичним. Оновлення моделі змінює точність виконання довгих інструкцій. Інструмент командного рядка, який викликає навичка, перейменовує прапорець. URL у файлі довідкових матеріалів починає повертати 404, і агент працює зі сторінкою помилки.

У жодному з цих випадків не виникає явної помилки. Агент і далі відповідає. Просто відповідь стає гіршою, ніж минулого місяця. Це важко помітити, коли зміни надходять по одному pull request.

Що вирішують інструменти, випущені у 2026 році

Кілька рішень уже доступні, і вони по-різному визначають, де має зберігатися версія.

Lockfiles. Інструмент командного рядка skills від Vercel Labs (vercel-labs/skills, ліцензія MIT, версія v1.5.22 станом на 5 August 2026) встановлює skills із git-репозиторію в каталог, якого очікує ваш agent, і підтримує структуру більш ніж сімдесяти agents. npx skills add <repo> встановлює, npx skills update оновлює, а npx skills list показує встановлені компоненти. Перелік встановленого зберігається один раз на користувача, а не окремо для кожного репозиторію. Відкритий запит у цьому проєкті (issue 283) пропонує додати команду skills install, яка повторно встановлює всі відстежувані skills із lock file, щоб на другій машині отримати той самий набір. Розглядайте цей запит як звіт про поточний стан. Ідея lock file вже усталена. Варіант для окремого проєкту ще розробляється.

Specs і тести. SkillSpec використовує інший підхід. Він розглядає SKILL.md як контракт, який потрібно перевіряти, а не як текст, якому слід довіряти. Заявлена мета — зробити skills «такими, яких можна дотримуватися, тестувати й доводити». skillspec doctor <path> показує, де agent найімовірніше втратить контекст. skillspec boundary map <path> показує, до яких ресурсів може отримати доступ skill, а skillspec boundary assess <path> ранжує ці результати за ризиком. Це Rust crate із подвійною ліцензією MIT або Apache 2.0, версія 0.2.2 станом на 29 July 2026. Встановлюйте зафіксовану версію, а не найновішу:

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

--locked збирає пакет із версіями залежностей, з якими crate було опубліковано, тому версії під час збірки не змінюються непередбачувано. skillspec --version має вивести 0.2.2. Інше число означає, що у вашому PATH використовується старіший binary.

Практика вендора. Google описала процес складання skills у google/skills у дописі про створення, тестування та масштабування agent skills. Якщо не враховувати масштаб, механізм є звичайною continuous integration (CI). Перед злиттям кожен skill проходить linters, які перевіряють frontmatter metadata, кількість рядків, структуру каталогів і найменування. Link checker завершує збірку з помилкою для будь-якого URL, що повертає 404, і виявляє правдоподібні посилання, вигадані agent. Автори мають додати до skill набір evaluation prompts і scoring rubric. Заплановані evaluation jobs щотижня запускаються для всієї бібліотеки, щоб виявляти регресії. Для кожного skill призначено owner, який має виправляти його, якщо якість знижується.

Шаблон, спільний для всіх трьох відповідей

Не обов’язково обирати один із цих варіантів. За ними стоїть єдина структура, і звичайний git надає всі потрібні можливості.

  1. Єдине джерело істини. У навички є рівно одне місце зберігання, а кожен репозиторій посилається на нього замість зберігання копії.
  2. Зафіксована версія для кожного репозиторію. Кожен проєкт записує точну ревізію, яку використовує. Тому оновлення є комітом у цьому проєкті із зазначеними автором і датою.
  3. Smoke test для кожної навички. Одна перевірка, яку можна запустити, підтверджує, що навичка й надалі видає обіцяний результат.
  4. Шлях перевірки. Зміна спільної навички проходить review, а кожен споживач бачить diff перед її підключенням.

Так виглядає залежність. Навички стали спільними артефактами швидше, ніж для них з’явилися відповідні інструменти. Тому найбезпечніше використовувати вже перевірені інструменти.

Макет для невеликої команди на self-hosted git remote

Один репозиторій містить інструкції. Більше в ньому нічого немає, тому його історія має вигляд журналу змін інструкцій.

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

Якщо ваш remote — це Gitea, Forgejo, GitLab або bare repository через SSH на власному VPS, далі нічого не змінюється. Усе зводиться до git і символічного посилання.

Фіксація версії за допомогою git submodule

Submodule записує один точний commit іншого репозиторію у вашому репозиторії. Цей запис і є зафіксованою версією. У кожному проєкті, який його використовує:

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"

Саме symlink забезпечує цю схему. Запис skill на рівні проєкту може бути symlink на каталог в іншому місці диска, а Claude Code переходить за ним і читає SKILL.md із цільового каталогу. Тому skill завантажується як звичайний проєктний skill, а його файли зберігаються в submodule на commit, який ви вибрали.

Перевірте зафіксовану версію:

git submodule status

Коректний рядок починається з пробілу, далі містить commit, path і найближчий tag:

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

Початковий - означає, що submodule ще не ініціалізовано, тому .claude/skills/api-review ні на що не вказує, а skill непомітно не завантажується. Виправте це за допомогою git submodule update --init. Початковий + означає, що перевірений commit відрізняється від записаного, тому цей розробник використовує інструкції, яких немає в інших. Для нових клонів потрібна команда 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 призначений для перевірки змін. Він показує ту саму зміну, яку побачать усі інші проєкти, що використовують цей submodule, і його можна включити до pull request.

Натомість зафіксуйте версію через marketplace плагінів

Якщо ви не хочете, щоб кожен розробник вивчав submodules, система плагінів Claude Code сама виконує розповсюдження та працює із self-hosted remote. Додайте каталог у .claude-plugin/marketplace.json у репозиторії skills:

{
  "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"
      }
    }
  ]
}

Тут використовуються два різні джерела, і саме їх плутання є типовою помилкою. Джерело marketplace, тобто місце, звідки отримується сам каталог, приймає ref для гілки або тегу, але не приймає sha. Джерело плагіна всередині каталогу приймає обидва параметри. Якщо задано обидва, ефективною фіксацією є sha. Тому exact-commit pin потрібно вказувати в записі каталогу.

Кожен репозиторій, що використовує плагін, оголошує marketplace у своєму закоміченому .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
  }
}

Колезі, який довіряє папці проєкту, буде запропоновано встановити marketplace, після чого плагін увімкнеться для нього без wiki-сторінки з відповідною інструкцією. Після цього skills доступні через /team-skills:api-review, оскільки skills плагіна мають простір імен за назвою плагіна та не конфліктують із project skill з такою самою назвою. Після надсилання нового тегу споживачі оновлюють marketplace за допомогою /plugin marketplace update acme-agents, а потім виконують /reload-plugins, якщо це вказано у зведенні результатів інсталяції.

Написання smoke test для однієї skill

Smoke test — це скриптований запуск агента на fixture із відомою несправністю та однією перевіркою. Claude Code працює в неінтерактивному режимі з -p, а skill, який викликає користувач, у цьому режимі працює: додайте /skill-name до рядка prompt, і його буде розгорнуто до початку запуску.

#!/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 — це короткий файл з однією навмисно внесеною несправністю. Перевірка полягає в тому, що skill називає цю несправність. jq -e завершується з ненульовим кодом, коли його filter повертає null, тому skill, який перестав виявляти підготовлену несправність, спричиняє помилку скрипту. claude сам завершується з ненульовим кодом, коли запуск завершується помилкою, а set -euo pipefail перетворює будь-яку з цих помилок на невдалий тест.

Модель змінює формулювання відповідей між запусками, тому ніколи не перевіряйте повне речення. Перевіряйте ідентифікатор, який має вивести skill, або поле схеми, яку ви запросили. Fixture має бути невеликою, щоб запуск залишався недорогим.

У CI додайте --bare. Без нього claude -p завантажує той самий контекст, що й інтерактивний сеанс, зокрема hooks, plugins і CLAUDE.md із машини, на якій він працює. Через це персональна конфігурація іншого учасника команди може змінити результат. Bare mode пропускає автоматичне виявлення, тому він також пропускає skill, який ви тестуєте. Завантажте цей skill явно. Bare mode також не читає дані входу до вашої subscription, тому спочатку задайте в середовищі 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 перша подія запуску повідомляє, які plugins завантажено, і містить масив plugin_errors для тих, які не завантажилися. Завершуйте завдання CI з помилкою, якщо plugin_errors не порожній. Це виявляє pin, спрямований на revision, якого більше не існує. Без цього проблема проявляється лише в тому, що агент мовчки ігнорує внутрішні правила команди.

Спільний skill — це виконувана інструкція

Дві можливості роблять це буквальним фактом, і обидві мають значення, коли файл надходить від іншої команди.

По-перше, SKILL.md може виконувати shell-команди до того, як модель щось прочитає. Рядок на кшталт цього в тексті є етапом попередньої обробки:

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

Команда виконується на машині, яка завантажує skill, а її вивід замінює placeholder у тексті, який отримує модель. Блок коду, відкритий трьома символами backtick із подальшим !, так само виконує кілька команд. Під час виконання ніхто не підтверджує ці дії. Читання спільного skill означає читання його підстановок команд.

По-друге, frontmatter може заздалегідь дозволяти використання інструментів. allowed-tools надає переліченим інструментам доступ без запиту дозволу протягом ходу, у якому було викликано skill. Для project skill цей дозвіл набуває чинності після того, як користувач приймає діалог підтвердження довіри до workspace для цієї папки. Документація Claude Code прямо описує наслідок: перевіряйте project skills перед тим, як довіряти репозиторію, оскільки skill може надати собі широкий доступ до інструментів.

Тому оновлення skill слід обробляти так само, як оновлення залежності. Усюди, де це дозволяє механізм, фіксуйте exact commit, оскільки tag можна перемістити, а branch за визначенням змінюється. На машині з обмеженим доступом "disableSkillShellExecution": true у settings замінює кожну підстановку команди на буквальний текст [shell command execution disabled by policy] замість її виконання, а в разі застосування через managed settings користувач не може це перевизначити. На bundled і managed skills це налаштування не поширюється.

Так само уважно потрібно ставитися до того, що читає skill. Skill, який виконує env або відкриває config file, передає в context моделі все, що знаходить. Саме цю проблему описано в як не передавати секрети агентам, яких ви запускаєте. Skill, який отримує сторінку або виконує запит, створює таку саму експозицію назовні, оскільки отриманий текст потрапляє в context і виглядає точно як написані вами інструкції. Це межа, про яку варто прочитати, перш ніж спрямувати агента до власного екземпляра SearXNG для вебпошуку.

Що читати під час оновлення версії

  • Diff кожного тіла SKILL.md, оскільки цей текст містить інструкції, яких дотримуватиметься ваш агент.
  • Кожну підстановку команд, оскільки вони виконуються на вашій машині під час завантаження skill.
  • Будь-яку зміну в allowed-tools, оскільки цей рядок надає інструменти без запиту.
  • Результат тестування, пов’язаний із tag. Якщо спільний repository запускає власні smoke-тести в CI, tag, до якого ви прив’язуєте версію, має містити успішний результат виконання.

Якщо reviewer не може прочитати весь diff за десять хвилин, він працює зі skill, який став надто великим. Розділіть його. Те саме стосується документів repository, які читають ваші агенти: зберігайте сталі правила у файлах, описаних у розділенні AGENTS.md і HUMAN.md, а архітектурні обґрунтування — у DESIGN.md, написаному для агентів, а skill залишайте вузькими процедурами.

Коли зміна моделі або інструмента ламає skill

Деякі компоненти, від яких залежить skill, змінюються без редагування самого skill. Оновлення моделі може змінити надійність виконання довгих інструкцій. Через це skill, який залежав від досягнення моделлю кроку дев’ять, може перестати до нього доходити. У інструменті командного рядка перейменували flag, тому агент запускає старий flag, читає помилку та імпровізує. URL, на який є посилання, починає повертати 404. Агентський harness змінює спосіб вибору skills, тому description, який раніше вигравав зіставлення, більше не виграє.

Саме тому в цій схемі smoke test має таке значення. Запускайте тест кожного skill за розкладом і після push. Google щотижня запускає свої evaluation jobs для всієї бібліотеки саме з цієї причини. Для команди з десятьма skills достатньо щотижневого cron job на невеликому VPS. Це єдиний спосіб дізнатися про збій до того, як його виявить розробник.

Портативність також допомагає. Специфікація Agent Skills обмежує frontmatter шістьма ключами. Тому skill, написаний відповідно до цієї специфікації, завантажується в інструментах, відмінних від того, для якого його створили. Кожен ключ, специфічний для певного harness, є залежністю від одного vendor. Написання skills, які працюють після заміни моделі, — це окрема дисципліна. Їй присвячено матеріал як зробити skill сумісним із будь-якою моделлю.

FAQ

Як надати одну навичку агента спільний доступ у кількох репозиторіях?

Розмістіть навичку в окремому git-репозиторії, створюйте в ньому теги релізів, а в кожному проекті-споживачі посилайтеся на тег замість копіювання файлу. Працюють два механізми. git submodule фіксує точний коміт, а symlink із .claude/skills/<name> у submodule дає змогу завантажувати навичку як звичайну навичку проекту. Marketplace плагінів виконує те саме завдання через /plugin, а pin-версія оголошується в .claude/settings.json репозиторію-споживача. В обох випадках версія зберігається в історії git, тому можна визначити, які інструкції сформували конкретний запуск агента.

Чи можна прив’язати навичку агента до певної версії?

Не зсередини SKILL.md, оскільки ця frontmatter не має ключа version. Pin-версія має надходити з рівня, що оточує файл. git submodule за задумом фіксує точний коміт. У marketplace плагінів Claude Code джерело плагіна приймає ref для гілки або тега та sha для точного коміту, причому sha має пріоритет, якщо задано обидва параметри. Саме джерело marketplace приймає лише ref. Віддавайте перевагу pin-версії коміту, оскільки тег можна перемістити після його перевірки.

Що має перевіряти smoke test навички?

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

Чи безпечно встановлювати спільну навичку з репозиторію іншої команди?

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

Чи працюватиме спільна навичка в агентах, відмінних від Claude Code?

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

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