Metadata-Version: 2.4
Name: cocoaskills
Version: 0.14.1
Summary: Local skill manager for AI agent skills with reproducible per-project installs
Author-email: Ivan Oparin <oparin@me.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/ivanopcode/cocoaskills
Project-URL: Source, https://github.com/ivanopcode/cocoaskills
Project-URL: Issues, https://github.com/ivanopcode/cocoaskills/issues
Project-URL: Changelog, https://github.com/ivanopcode/cocoaskills/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/ivanopcode/cocoaskills/blob/main/docs/mvp-design.md
Keywords: skills,ai-agents,claude-code,cursor,codex,gemini,dependency-manager
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=9; extra == "dev"
Requires-Dist: pytest-xdist<4,>=3.8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: mypy>=1.14; extra == "dev"
Requires-Dist: cryptography>=44; extra == "dev"
Requires-Dist: jsonschema>=4.23; extra == "dev"
Dynamic: license-file

# CocoaSkills

[![PyPI](https://img.shields.io/pypi/v/cocoaskills.svg)](https://pypi.org/project/cocoaskills/)
[![Python versions](https://img.shields.io/pypi/pyversions/cocoaskills.svg)](https://pypi.org/project/cocoaskills/)
[![License](https://img.shields.io/pypi/l/cocoaskills.svg)](https://github.com/ivanopcode/cocoaskills/blob/main/LICENSE)
[![CI](https://github.com/ivanopcode/cocoaskills/actions/workflows/ci.yml/badge.svg)](https://github.com/ivanopcode/cocoaskills/actions/workflows/ci.yml)

Установщик `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

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

| Решение | Основной фокус | Сильная сторона | Ограничения для задач компании |
| --- | --- | --- | --- |
| Vercel (skills.sh) | Каталог и установка публичных навыков | Масштаб экосистемы и поддержка множества агентов | Ориентация на публичное распространение без защиты корпоративной цепочки поставки |
| SkillKit | Универсальное управление для разных агентов | Разнообразие интеграций, поиск и сканирование безопасности | Уклон в индивидуальное использование без детерминированной воспроизводимости графа зависимостей |
| Tessl | Корпоративное управление и реестр | Приватные навыки, правила аудита и оценка качества | Зависимость от централизованной платформы вместо локального менеджера пакетов |
| NVIDIA Skills / SkillSpector | Безопасность, подлинность и проверка качества | Цифровые подписи, сканирование угроз и бенчмарки | Проверка и публикация без управления полным жизненным циклом локального окружения |
| Agent Plugins | Открытый формат пакета | Объединение навыков и инструментов MCP в единый стандарт | Спецификация формата без функций установки, разрешения зависимостей и контроля правил |

Установщик `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 одним из способов:

   <details open>
   <summary>pipx (рекомендуется)</summary>

   ```bash
   pipx install cocoaskills
   ```

   </details>

   <details>
   <summary>uv tool</summary>

   ```bash
   uv tool install cocoaskills
   ```

   </details>

   <details>
   <summary>Homebrew (macOS, Linux)</summary>

   ```bash
   brew tap ivanopcode/csk
   brew install cocoaskills
   ```

   </details>

   <details>
   <summary>mise</summary>

   ```bash
   mise use -g pipx:cocoaskills@latest
   ```

   </details>

   <details>
   <summary>pip</summary>

   ```bash
   python -m pip install --user cocoaskills
   ```

   </details>

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

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

   ```bash
   cd /path/to/project
   csk init
   ```

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

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

   ```bash
   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. Выполните установку объявленных скиллов:

   ```bash
   csk install
   ```

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

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

   ```bash
   claude
   ```

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

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

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

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

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

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

```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`.

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

```bash
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-репозиторий. Платформенные команды используют гибридный режим для раскатки процессных правил и рабочих процессов на выбранные репозитории.

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

```bash
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` по пяти функциональным группам.

<details>
<summary>Проект</summary>

```bash
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]        # Показывает резолюцию манифеста и целевых путей
```

</details>

<details>
<summary>Скиллы и зависимости</summary>

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

</details>

<details>
<summary>Global и Hybrid</summary>

```bash
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                   # Показывает статус гибридных скиллов и хранилища
```

</details>

<details>
<summary>Сборки и аудит</summary>

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

</details>

<details>
<summary>Сервисные</summary>

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

</details>

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

## Дальше

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

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

## Лицензия

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