Делимся навыками

Навык, который лежит только у вас в ~/.claude/skills/, — это личная привычка. Стандартом он становится, когда есть у всех и обновляется в одном месте. В этом уроке — как это устроить: от простого коммита в репозиторий до маркетплейса плагинов агентства.

Уровень 1. Репозиторий проекта

Самый простой и чаще всего достаточный путь: положить навык в .claude/skills/ проекта и закоммитить.

git add .claude/skills/release-notes
git commit -m "Навык release-notes: релиз-ноты по шаблону команды"

Каждый, кто клонирует проект, получает навык. Изменения проходят через merge request и ревью — как код. Если навык сломали, это видно в истории.

Что стоит проверить перед коммитом:

• allowed-tools. Проектный навык применяет свои разрешения при каждом вызове, независимо от доверия к папке. Навык с allowed-tools: Bash(*) в чужом репозитории — это открытая дверь. Ревьюер должен смотреть на эту строку так же внимательно, как на изменения в CI.
• Секреты. В навык не должны попадать токены, адреса внутренних серверов с паролями, персональные данные. Навык — публичный текст внутри репозитория.
• Пути. Скрипты вызывайте через ${CLAUDE_SKILL_DIR}, а не через абсолютные пути с вашего компьютера.

Ограничение этого уровня очевидно: навык живёт в одном проекте. Если у агентства двадцать репозиториев и навык релиз-нот нужен во всех, придётся копировать и потом синхронизировать двадцать копий. Для этого есть следующий уровень.

Уровень 2. Плагин

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

Структура минимального плагина с двумя навыками:

amiga-standards/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── release-notes/
    │   └── SKILL.md
    └── a11y-check/
        ├── SKILL.md
        ├── checklist.md
        └── scripts/
            └── contrast.py

Манифест .claude-plugin/plugin.json:

{
  "name": "amiga-standards",
  "description": "Командные стандарты Amiga: релиз-ноты, проверка доступности",
  "version": "1.0.0",
  "author": {
    "name": "Amiga"
  }
}

Важная деталь: внутри .claude-plugin/ лежит только манифест. Папки skills/, agents/, hooks/ — в корне плагина, не внутри .claude-plugin/. Это самая частая ошибка при сборке.

Навыки плагина получают префикс: /amiga-standards:release-notes. Пространство имён гарантирует, что навык из плагина не конфликтует ни с проектными, ни с личными. Для плагинных навыков поле name в шапке задаёт последнюю часть команды; для проектных и личных, напомним, команда берётся из имени папки.

Проверить плагин локально, не устанавливая:

claude --plugin-dir ./amiga-standards

После правок — /reload-plugins, чтобы подхватить изменения без перезапуска. Перед публикацией — claude plugin validate ./amiga-standards: проверит структуру и синтаксис шапок.

Если у вас уже есть навыки в .claude/ проекта, их можно перенести в плагин копированием папок; документация описывает это как штатный путь. После переноса оригиналы из .claude/skills/ стоит удалить, иначе будут доступны оба варианта — /release-notes и /amiga-standards:release-notes.

Уровень 2½. Маркетплейс

Плагин нужно откуда-то устанавливать. Для этого есть маркетплейс — каталог плагинов, обычно git-репозиторий с файлом .claude-plugin/marketplace.json:

{
  "name": "amiga-plugins",
  "owner": {
    "name": "Amiga"
  },
  "plugins": [
    {
      "name": "amiga-standards",
      "source": "./plugins/amiga-standards",
      "description": "Командные стандарты: релиз-ноты, проверка доступности",
      "version": "1.0.0"
    }
  ]
}

Плагины лежат в подпапках того же репозитория, source — относительный путь. Репозиторий может быть приватным: Claude Code использует ваши git-учётные данные.

Сотрудник добавляет маркетплейс и ставит плагин:

/plugin marketplace add amiga/claude-plugins
/plugin install amiga-standards@amiga-plugins

При установке выбирается область: только для себя во всех проектах, для всех участников этого репозитория или только для себя в этом репозитории. Обновления приходят, когда вы поднимаете version в манифесте.

Чтобы не просить каждого добавлять маркетплейс руками, его можно прописать в .claude/settings.json проекта:

{
  "extraKnownMarketplaces": {
    "amiga-plugins": {
      "source": {
        "source": "github",
        "repo": "amiga/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "amiga-standards@amiga-plugins": true
  }
}

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

Уровень 3. Организация

Для агентства целиком есть управляемые настройки — их разворачивает IT через MDM или аналог, и отдельные сотрудники их отменить не могут. На этом уровне можно:

• разложить навыки в папку .claude/skills/ управляемой директории — они будут у всех и имеют высший приоритет при совпадении имён;
• ограничить список маркетплейсов, откуда разрешено ставить плагины, через strictKnownMarketplaces — например, только репозитории организации;
• централизованно включить плагины через те же extraKnownMarketplaces и enabledPlugins в управляемых настройках, с автообновлением.

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

Личные навыки между проектами

Навык в ~/.claude/skills/ доступен во всех ваших проектах на этой машине. Для личных привычек это лучшее место. Есть и другой путь: команда claude plugin init my-tool создаёт в ~/.claude/skills/my-tool/ заготовку плагина с манифестом, и он подхватывается автоматически как my-tool@skills-dir, без маркетплейса и установки. Удобно, когда личный навык перерос один файл.

Ещё навыки можно включить для своего аккаунта claude.ai — тогда они доступны в Cowork и облачных сессиях. На локальную машину их нужно один раз скачать неинтерактивным запуском с переменной CLAUDE_CODE_SYNC_SKILLS=1. У синхронизированных навыков есть ограничения: они не выполняют команды !`…` и не подставляют часть переменных. Для командных стандартов надёжнее репозиторий и плагин.

Что выбрать

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