CocoaSkills

Установщик csk управляет локальными пакетами скиллов для AI-агентов. Инструмент загружает скиллы из git-репозиториев и подготавливает файлы для шести сред: Claude Code, Codex CLI, Cursor, Gemini, OpenCode и Windsurf.

Зачем

Ручное управление скиллами в нескольких проектах создаёт проблемы при командной разработке. Содержимое файлов на компьютерах разработчиков расходится со временем. Без фиксации версий по тегам и коммитам обновления ломают рабочие окружения. Вспомогательные файлы, такие как README, тесты и файлы сборки, попадают в контекст агента и расходуют лимиты токенов. При удалении скилла из конфигурации неиспользуемые файлы остаются на диске.

Установщик csk решает эти проблемы декларативным описанием скиллов в Skillfile.json. Инструмент фиксирует версии git-репозиториев, копирует в контекст агента только SKILL.md и объявленные каталоги (references/, assets/, agents/, data/), исключая tests, README, файлы сборки и метаданные git, и удаляет устаревшие файлы при обновлении состава скиллов.

Рынок и позиция CocoaSkills

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

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

• Детерминированный граф зависимостей выявляет конфликты версий до начала установки.
• Поддержка закрытых источников позволяет ограничить загрузку разрешёнными git-репозиториями.
• Трёхуровневая изоляция разделяет контекст модели, исполняемую среду и артефакты сборки.
• Транзакционная установка гарантирует откат к исходному состоянию при ошибках.
• Каноническое состояние проекта не зависит от выбранного агента или среды разработки.
• Локальная проверка правил безопасности работает без обязательной связи с внешними сервисами.

Существующие инструменты решают задачи каталогизации и проверки навыков; csk закрывает соседний уровень: детерминированную и воспроизводимую установку скиллов внутри закрытого корпоративного контура.

Почему CocoaSkills, а не альтернативы

Ручное копирование папок или создание symlink:

• Где ломается: требует повторного копирования во всех проектах при обновлениях и переносит лишние файлы репозитория в контекст модели.
• Что делает csk: автоматизирует загрузку, фильтрует содержимое до разрешённых каталогов и обновляет файлы одной командой.

Подключение через git submodules или git subtree:

• Где ломается: сохраняет полную историю репозиториев, требует команд git при переключении веток и не формирует адаптеры для агентов.
• Что делает csk: скачивает репозитории в локальный кэш, извлекает файлы скиллов и строит конфигурации для каждого агента.

Встроенные маркетплейсы плагинов внутри конкретных агентов:

• Где ломается: привязывает скиллы к одному агенту и не позволяет использовать единый манифест в командах с разными инструментами.
• Что делает csk: хранит единый Skillfile.json и раскладывает скиллы по адаптерам Claude Code, Codex CLI, Cursor и Gemini; OpenCode и Windsurf читают .agents/skills/ напрямую.

Общая директория скиллов с синхронизацией кастомными скриптами:

• Где ломается: требует поддержки собственных скриптов, не проверяет контрольные суммы и не управляет транзитивными зависимостями.
• Что делает csk: вычисляет граф зависимостей скиллов, фиксирует точные хеши содержимого и изолирует сгенерированные файлы.

Инструмент CocoaSkills не служит публичным реестром пакетов, не выступает runtime-средой для агента и не управляет MCP-серверами. Установщик отвечает только за декларативную доставку и локальную раскладку файлов скиллов.

Быстрый старт

1. Установите CocoaSkills одним из способов:

   pipx (рекомендуется)

   pipx install cocoaskills
   

   uv tool

   uv tool install cocoaskills
   

   Homebrew (macOS, Linux)

   brew tap ivanopcode/csk
   brew install cocoaskills
   

   mise

   mise use -g pipx:cocoaskills@latest
   

   pip

   python -m pip install --user cocoaskills
   

   Результат: команда csk --version выводит версию CocoaSkills.

2. Перейдите в каталог проекта и инициализируйте конфигурацию:

   cd /path/to/project
   csk init
   

   Результат: команда создаёт манифест Skillfile.json с начальной конфигурацией проекта и записывает блок директорий .agents/, .claude/skills/, .codex/skills/, .cursor/rules/, .gemini/skills/ и файла Skillfile.dev.json в .gitignore.

3. Добавьте объявление скилла в проект:

   csk add skill-tracker --git git@gitlab.example.com:skills/skill-tracker.git --tag v1.0.0
   

   Результат: команда записывает объект скилла с именем skill-tracker, указанным репозиторием и тегом v1.0.0 в массив skills файла Skillfile.json.

4. Выполните установку объявленных скиллов:

   csk install
   

   Результат: установщик скачивает репозиторий, извлекает файлы скилла в .agents/skills/skill-tracker/, генерирует адаптеры для указанных агентов и создаёт исполняемые шимы в .agents/bin/ для скиллов с командами.

5. Проверьте доступность скилла в подключённом агенте:

   claude
   

   Результат: агент считывает инструкции из адаптера .claude/skills/ и применяет правила скилла skill-tracker в текущей сессии.

Приватные репозитории сборки: за один Enter

Скомпилированные команды скилла могут собираться из отдельно запиненного git-репозитория. Если репозиторий приватный, при первой установке csk показывает обнаруженные варианты (ssh-agent, ваши *.pub): вы выбираете вариант на терминале (по умолчанию предлагается вариант "агент + пин ключа"), указываете скоуп, и выбор сохраняется в конфиг. В CI то же самое задаётся заранее:

csk config build-ssh add gitlab.example.com/portals/infra \
    --agent auto --identity ~/.ssh/work.pub

Приватный репозиторий сборки работает и по SSH, и по HTTPS. Для HTTPS ничего заводить не нужно, если вы уже клонируете по HTTPS: csk предложит переиспользовать ваши собственные креды Git при первой установке за один Enter. Для неинтерактивного случая выполните команду:

csk config build-https add gitlab.example.com/portals/infra --token git-credentials

В CI задайте переменную CSK_BUILD_HTTPS_TOKEN (и CSK_BUILD_HTTPS_HOST, если репозитории сборки живут на разных хостах).

Пакет скилла выбрать креды не может: выбор делает только оператор и только явно. Подробности устройства брокеров кредов и скоупов описаны в docs/external-build-repositories.md.

Режимы установки скиллов

Установщик поддерживает три режима установки скиллов в зависимости от зоны ответственности и способа распространения файлов.

Проектный режим

Проектный режим фиксирует скиллы в файле Skillfile.json в корне репозитория. Разработчики коммитят этот файл в систему контроля версий. Вызов csk install на любой машине разворачивает одинаковый набор скиллов для всех участников команды.

Файл Skillfile.json поддерживается в двух вариантах схемы.

Схема 2 является основным форматом проектного Skillfile. Она объявляет источники и выбирает скиллы через селекторы. Команды csk check, csk install, csk upgrade и csk status поддерживают её по умолчанию.

Пример Skillfile.json схемы 2:

{
  "schema_version": 2,
  "project": { "alias": "demo-ios" },
  "agents": ["claude_code", "codex_cli", "cursor"],
  "sources": {
    "local": { "path": "." }
  },
  "skills": [
    {
      "name": "skill-tracker",
      "from": "local",
      "directory": "skills/skill-tracker"
    }
  ]
}

При работе со схемой 2 команда csk install выполняет начальную установку или устанавливает по файлу Skillfile.lock.json, команда csk upgrade явно обновляет лок, а csk status показывает актуальность манифеста и лока без записи. Команда csk check проверяет Skillfile без установки. Сетевые источники подчиняются файлу source-policy.json, который находится в ~/.cocoaskills/source-policy.json (путь переопределяется через CSK_SOURCE_POLICY). Подробное описание работы со схемой 2 приведено в docs/skillfile-sources.md.

Коммитьте Skillfile.lock.json вместе со Skillfile.json. На новой машине csk install восстанавливает отсутствующий снимок. Для path команда читает текущие байты. Для git и repository она получает точный commit из лока. Установка продолжится при совпадении идентичности и content_sha256. Расхождение вызывает source_snapshot_changed. Недоступный источник вызывает source_snapshot_unavailable и указывается в сообщении. Восстановление не меняет лок и не разрешает теги или ветки. csk upgrade явно обновляет лок по текущим источникам.

Схема 1 остаётся поддерживаемым legacy-форматом. Она напрямую объявляет список скиллов в секции skills:

{
  "schema_version": 1,
  "project": { "alias": "demo-ios" },
  "agents": ["claude_code", "codex_cli", "cursor"],
  "skills": [
    {
      "name": "skill-tracker",
      "git": "git@gitlab.example.com:skills/skill-tracker.git",
      "tag": "v1.0.0"
    }
  ]
}

Глобальный режим

Глобальный режим устанавливает скиллы один раз на компьютере пользователя в каталог ~/.cocoaskills/global/. Глобальные скиллы работают во всех каталогах вне зависимости от наличия git-репозитория и файла Skillfile.json.

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

csk global add skill-metrics --git git@gitlab.example.com:skills/skill-metrics.git --tag v2.1.0

Команда csk global install скачивает репозиторий и записывает адаптеры в пользовательские директории агентов в домашнем каталоге.

Гибридный режим

Гибридный режим объявляет скиллы один раз на машине в файле ~/.cocoaskills/hybrid/Skillfile.json и активирует их для целевых проектов по алиасу, пути или глоб-шаблону. Установщик создаёт адаптеры в директориях агентов проекта (.claude/skills/, .codex/skills/) и шимы команд в .agents/bin/, но не требует коммитов в git-репозиторий. Платформенные команды используют гибридный режим для раскатки процессных правил и рабочих процессов на выбранные репозитории.

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

csk hybrid add workflow-lint --git git@gitlab.example.com:skills/workflow-lint.git --tag v1.2.0 --target "demo-ios"

При запуске csk install внутри проекта demo-ios установщик проверяет правила в ~/.cocoaskills/hybrid/Skillfile.json, находит совпадение по алиасу demo-ios и подключает скилл workflow-lint в локальный контекст агентов.

Порядок перекрытия скиллов

При совпадении имён скиллов в разных режимах установщик применяет следующий порядок приоритета: проектный режим перекрывает гибридный режим, а гибридный режим перекрывает глобальный режим (проектный > гибридный > глобальный).

Команды

Раздел содержит обзор основных команд csk по пяти функциональным группам.

csk init [path]                     # Инициализирует Skillfile.json и .gitignore в проекте
csk add <name>                      # Добавляет или обновляет объявление скилла в Skillfile.json
csk remove <name>                   # Удаляет объявление скилла из Skillfile.json
csk status [target]                 # Показывает статус установленных скиллов и манифеста
csk check [target]                  # Проверяет Skillfile без установки
csk list                            # Выводит список зарегистрированных проектов и скиллов
csk project add <alias> <path>      # Регистрирует путь проекта в глобальной конфигурации
csk project resolve [target]        # Показывает резолюцию манифеста и целевых путей

csk install [target]                # Устанавливает объявленные скиллы по локальным git-ссылкам
csk update                          # Выполняет git fetch для всех источников в skills_root
csk upgrade [target]                # Подтягивает обновления источников и выполняет установку
csk skill check <dir>               # Проверяет валидность структуры скилла и SKILL.md

csk global init                     # Создаёт глобальный манифест ~/.cocoaskills/global/Skillfile.json
csk global add <name>               # Добавляет объявление скилла в глобальный манифест
csk global remove <name>            # Удаляет скилл из глобального манифеста
csk global list                     # Выводит список объявленных глобальных скиллов
csk global status                   # Показывает статус установки глобальных скиллов
csk global install                  # Устанавливает глобальные скиллы в профиль пользователя
csk global update                   # Подтягивает git-источники глобальных скиллов
csk global upgrade                  # Подтягивает git-источники и устанавливает глобальные скиллы
csk hybrid add <name>               # Связывает гибридный скилл с целевыми проектами
csk hybrid remove <name>            # Удаляет объявление гибридного скилла
csk hybrid list                     # Выводит список гибридных скиллов и привязок
csk hybrid status                   # Показывает статус гибридных скиллов и хранилища

csk audit [target]                  # Запускает статический аудит безопасности скиллов
csk gc                              # Очищает неиспользуемые runtime-записи и кэш сборок

csk bootstrap                       # Создаёт глобальную конфигурацию ~/.cocoaskills/config.json
csk config show                     # Выводит путь и содержимое текущей конфигурации
csk shell-init                      # Генерирует или устанавливает код хука shell для PATH

Полное описание команд, флагов, позиционных аргументов и примеров использования находится в файле docs/cli.md.

Источники Skillfile schema 2

Схема 2 является основным форматом проектного Skillfile и поддерживается командами csk check, csk install, csk upgrade и csk status без дополнительной настройки. Схема 1 остаётся поддерживаемым legacy-форматом.

Настройка experimental.skillfile_sources и переменная CSK_EXPERIMENTAL_SKILLFILE_SOURCES сохраняют совместимость со старыми конфигурациями и не влияют на выбор схемы.

Команды переиспользуют общий интерфейс: csk install выполняет начальную установку или установку по локу, csk upgrade явно обновляет лок, csk status показывает актуальность без записи, а csk check проверяет Skillfile без установки. Команды установки читают источники path с диска, а источники git и repository получают через ограниченный транспорт по машинной политике source-policy.json. Руководство для авторов и операторов находится в docs/skillfile-sources.md. Историческое решение зафиксировано в RFC 0009.

Development tools

• uv installs the development environment and builds release artifacts. Run uv sync --extra dev and uv build --out-dir .temp/dist; build outputs stay under .temp/dist/.
• pytest and pytest-xdist run the test suite. Run uv run pytest -q for the full suite or focused test paths; temporary output belongs under .temp/ or an external short-lived temp directory.
• mypy performs strict source type checking. Run uv run mypy; it writes no persistent artifact unless output is redirected to .temp/.
• PyYAML используется только в dev extra как независимый oracle для дифференциальных тестов frontmatter. Запускайте uv run pytest -q tests/test_frontmatter_differential.py; постоянные артефакты теста не создаются.
• actionlint validates GitHub Actions workflows. Run actionlint .github/workflows/ci.yml; validation logs belong under .temp/.
• GitHub Actions runs the cross-platform CI matrices. The merge protocol lane keeps full Linux/macOS coverage and uses the checked-in .research/ manifest, classification, and verifier for six deterministic Windows shards. Each Windows shard uploads its collected inventory, selected node IDs, verifier provenance, and JUnit XML as a workflow artifact.

Дальше

Документация и справочные материалы CocoaSkills:

• docs/cli.md: справочник команд csk, флагов и кодов завершения.
• docs/reference.md: справочник по матрице установки, зависимостям скиллов, манифестам и аудиту безопасности.
• docs/external-build-repositories.md: устройство внешних репозиториев сборки, брокеров кредов SSH/HTTPS и моделей доступа.
• docs/skillfile-sources.md: источники Skillfile schema 2, машинная транспортная политика и семантика лока.
• docs/v0.16-design.md: RFC 0009, запись проектного решения о формате источников schema 2 (на английском).
• ARCHITECTURE.md: описание внутренней архитектуры, схемы работы конвейера установки, формата хранилищ и модели безопасности.
• SECURITY.md: политика безопасности, границы изоляции и рекомендации по настройке.
• docs/skill-authoring.md: руководство по структурированию пакетов скиллов, объявлению команд и настройке манифеста agent-skill.json.
• docs/authoring-cli-commands.md: руководство по поставке CLI-утилит в скиллах (Go, скрипт-команды, ограничения компилятора и планируемые языки).
• docs/troubleshooting.md: диагностика ошибок установки, миграция со старых версий и решение частых проблем.
• CHANGELOG.md: история релизов и список изменений по версиям.

Лицензия

Проект распространяется на условиях лицензии Apache 2.0.