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 в текущей сессии.

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

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

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

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

Файл Skillfile.json с проектным скиллом выглядит следующим образом:

{
  "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 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.

Дальше

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

• docs/cli.md: справочник команд csk, флагов и кодов завершения.
• docs/reference.md: справочник по матрице установки, зависимостям скиллов, манифестам и аудиту безопасности.
• ARCHITECTURE.md: описание внутренней архитектуры, схемы работы pipeline установки, формата хранилищ и модели безопасности.
• SECURITY.md: политика безопасности, границы изоляции и рекомендации по настройке.
• docs/skill-authoring.md: руководство по структурированию пакетов скиллов, объявлению команд и настройке манифеста agent-skill.json.
• CHANGELOG.md: история релизов и список изменений по версиям.

Лицензия

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