Если Skill содержит команды сборки, правила тестирования, структуру каталогов или соглашения конкретного продукта, размещайте его на уровне проекта. Такой файл меняется вместе с кодом и проходит тот же review.

Если Skill описывает независимую от репозитория процедуру — например, формат технического отчёта или общую проверку лицензий — его можно разместить глобально для пользователя.

Если Skill должен быть одинаковым у команды, не копируйте его вручную в домашний каталог каждого сотрудника. Поддерживайте общий источник с историей версий, а в проект подключайте только одобренную редакцию. Это снижает риск скрытого расхождения между рабочими станциями.

DeepSeek Harness официально описывает локального файлового провайдера Skills, который может работать с проектными и пользовательскими корнями, общим корнем агентов и дополнительными каталогами. В конфигурации также предусмотрены параметры наблюдения за изменениями и обработки символических ссылок. См. официальный каталог конфигурации DeepSeek Harness.

Глобальный Skill удобен только до тех пор, пока его область действия действительно универсальна. На практике возникают минимум четыре ограничения.

Первое — скрытая зависимость от проекта. В инструкции может появиться путь вроде packages/api, команда внутреннего сборщика или имя переменной окружения. В первом репозитории это работает, а во втором агент начинает искать несуществующие файлы, менять неправильные конфигурации или пропускать обязательный шаг.

Второе — распространение изменений. Обновление глобального SKILL.md влияет на все проекты пользователя. Исправление, сделанное ради одного репозитория, становится поведенческим изменением для остальных. Если параллельно открыто несколько задач, определить причину разницы в ответах становится сложнее.

Третье — неявная ответственность. Проектный Skill имеет владельца в истории коммитов. У глобального файла часто нет понятного процесса review. Через несколько недель уже неясно, кто изменил инструкцию, почему была добавлена команда и на какой версии инструментов она проверялась.

Четвёртое — граница доверия. Skill — это не просто справочный текст. Через него агент получает инструкции, которые могут направлять чтение файлов, запуск команд и загрузку дополнительных материалов. Официальный инструмент skill загружает полный текст выбранного навыка по точному имени из каталога сессии, поэтому источник самого каталога имеет значение. Это описано в официальном каталоге инструментов DeepSeek Harness.

Отдельно учитывайте секреты. Не помещайте в SKILL.md ключи API, токены, пароли, приватные URL и команды, которые раскрывают содержимое .env. Репозиторийный Skill должен быть безопасен для code review и клонирования. Секреты должны приходить через отдельный механизм учётных данных, а не через инструкции агенту.

Для независимого разработчика проектный уровень обычно является самым предсказуемым вариантом. Skill живёт рядом с кодом, а его изменение можно связать с конкретным commit, pull request и версией сборочного процесса.

Практичная структура выглядит так:

project/
├── .dsh/
│   └── skills/
│       └── release-check/
│           └── SKILL.md
├── src/
├── tests/
└── package.json

Название .dsh/skills здесь показано как организационный пример. Точный каталог зависит от настроек файлового провайдера. В официальной конфигурации предусмотрен параметр customSkillDirs, поэтому не следует механически переносить путь из другой среды без проверки текущего cordis.yml или профиля запуска.

Проектный вариант особенно оправдан, если Skill содержит:

• команды сборки именно этого приложения;
• обязательный порядок запуска тестов;
• правила миграций базы данных;
• соглашения по структуре pull request;
• ограничения на изменение отдельных директорий;
• инструкции для конкретной версии SDK или CI/CD.

Преимущества проектного размещения

• Воспроизводимость. Новый разработчик получает Skill вместе с репозиторием.
• Связь с версией кода. Изменение инструкции можно откатить вместе с несовместимым изменением приложения.
• Ограниченная область влияния. Ошибка не распространяется на все проекты пользователя.
• Прозрачный review. Владелец репозитория видит изменения в обычном процессе проверки.

Ограничения

• Один и тот же универсальный Skill может появиться в нескольких репозиториях.
• Командные исправления нужно доставлять в проекты отдельно.
• Если Skill содержит локальные абсолютные пути, переносимость всё равно будет плохой.

Поэтому проектное размещение не означает «складывать туда всё подряд». В репозитории должны оставаться только правила, которые действительно относятся к жизненному циклу этого проекта.

Пользовательский глобальный каталог подходит для навыка, который не знает ничего о конкретном репозитории. Хороший тест: можно ли открыть новый проект с другой структурой, другим языком и другим сборщиком, а Skill всё равно останется корректным?

К глобальному уровню обычно относятся:

• единый формат заметок о работе агента;
• общая проверка наличия лицензий;
• универсальная процедура анализа логов;
• правила оформления технической документации;
• личные предпочтения по краткости отчётов;
• независимый от проекта аудит потенциальных секретов.

В конфигурации DeepSeek Harness домашний каталог задаётся через DSH_HOME, а при отсутствии явного значения используется стандартное значение, указанное в официальном каталоге конфигурации — $DSH_HOME или ~/.dsh. Файловый провайдер также отдельно описывает agentsHome: по умолчанию это $DSH_AGENTS_HOME или ~/.agents. Эти значения нельзя смешивать без проверки профиля запуска: домашний каталог Harness и общий каталог агентов — разные точки управления.

Что вы выигрываете

Глобальный Skill обновляется в одном месте. Для личной среды это удобно: вы не дублируете одинаковую инструкцию в пяти репозиториях и быстрее исправляете опечатки или устаревшую команду.

Чем платите

• Ложные срабатывания. Агент видит навык в проекте, где он не нужен.
• Версионный дрейф. Старый проект может ожидать одну версию команды, а глобальный Skill уже описывает другую.
• Расширение ущерба. Неудачная правка влияет на все рабочие каталоги.
• Сложность диагностики. Разработчик может не заметить, что поведение пришло не из репозитория, а из домашней среды.

Если глобальный Skill требует переменной, команды или инструмента, которые есть только на одном Mac, это уже не настоящий универсальный Skill. Перенесите его в проект или в отдельный управляемый источник.

Да, но лучше различать общий источник и общую изменяемую копию.

Несколько проектов могут использовать один Skill, если:

1. его правила не зависят от конкретного пути;
2. все проекты доверяют одному владельцу инструкции;
3. обновления проходят проверку;
4. есть понятный способ откатить изменение;
5. изменения не должны применяться к проектам в разное время.

Плохая схема — дать всем проектам доступ к одной изменяемой директории и разрешить каждому процессу записывать туда. В этом случае проект A может получить изменение, подготовленное для проекта B, ещё до завершения проверки. Ещё хуже — использовать символическую ссылку на рабочую копию разработчика: после локальной правки поведение меняется без изменения репозитория.

Для команды лучше держать исходные Skills в отдельном версионированном каталоге. В репозитории можно:

• синхронизировать утверждённую копию;
• подключать каталог только для чтения;
• фиксировать версию в конфигурации;
• хранить файл манифеста с владельцем и датой проверки.

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

Для небольшой команды оптимален не выбор «только проект» или «только глобально», а разделение ответственности.

Проектный слой содержит правила продукта:

• как собирать именно этот сервис;
• какие тесты обязательны перед merge;
• какие каталоги нельзя изменять автоматически;
• как оформлять миграции и релизы.

Общий слой только для чтения содержит утверждённые командные способности:

• единый анализ уязвимостей;
• стандартную проверку CI/CD;
• оформление incident report;
• процедуру ревью изменений агента;
• общие требования к журналированию.

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

Для каждой версии общего Skill зафиксируйте:

• идентификатор или commit;
• список изменений;
• проверенную версию DeepSeek Harness;
• совместимые инструменты;
• владельца;
• процедуру отката.

Если новая версия изменила команды или порядок действий, не заменяйте старый Skill «на месте». Сначала прогоните тестовое задание, затем обновите ссылку или синхронизированную копию в проекте.

В непрерывной среде Skills нельзя считать частью личного домашнего каталога. Если агент запускается в отдельном execution pool, контейнере или удалённом Mac, каталог пользователя может отсутствовать, быть непостоянным или отличаться между экземплярами.

Платформенная команда должна включать Skills в один из контролируемых этапов:

• образ среды;
• скрипт инициализации;
• пакет доставки рабочего окружения;
• подготовку конкретного рабочего каталога;
• монтирование утверждённого каталога только для чтения.

В конфигурации файлового провайдера официально предусмотрены customSkillDirs, watch, watchUsePolling, watchStabilityThresholdMs, watchPollIntervalMs, watchMaxProjects и watchFollowSymlinks. Это означает, что обнаружение и наблюдение за Skills — отдельная операционная задача, а не гарантированное свойство любой файловой системы. Подробные поля перечислены в разделе dsh-skill-filesystem.

Перед приёмкой удалённой среды проверьте пять вещей:

1. каталог реально существует внутри процесса Harness, а не только на хосте;
2. файл SKILL.md доступен тому же пользователю, под которым работает агент;
3. новый Skill появляется в каталоге после предусмотренного обновления;
4. перезапуск не удаляет или не теряет каталог;
5. два execution pool не видят изменения друг друга, если изоляция обязательна.

Не полагайтесь только на успешный ls. Нужно проверить полный цикл: создать тестовый Skill, открыть новую сессию, найти его точное имя, загрузить содержимое через инструмент skill, выполнить безопасное тестовое задание, затем перезапустить процесс и повторить проверку.

Чаще всего причина находится в одном из пяти мест.

Неправильный корень. Файл лежит в каталоге, который не включён в customSkillDirs, либо отключены стандартные корни параметром includeDefaultRoots: false.

Неверная структура. Провайдер ожидает Skill как каталог с SKILL.md, а не одиночный Markdown-файл, положенный прямо в корень.

Старая сессия. Каталог Skills может быть уже собран для текущего рабочего контекста. Если изменение не подхватилось наблюдателем, откройте новую сессию и повторите проверку.

Проблема с правами. Процесс видит каталог, но не может прочитать файл или пройти по одному из родительских каталогов.

Символическая ссылка. Ссылка указывает на недоступную, перемещённую или запрещённую директорию. При использовании ссылок отдельно проверьте параметр watchFollowSymlinks. Следование за ссылками влияет не только на обнаружение, но и на границу доверия: источник может находиться за пределами ожидаемого проекта.

Официальный исходный код файлового провайдера находится в пакете skill-filesystem. При изменении версии сначала сверяйте реализацию, а не переносите старые предположения о порядке сканирования и моменте обновления каталога.

В чувствительных проектах запрет на изменяемый глобальный каталог должен быть правилом по умолчанию. Особенно это важно, если один Mac обслуживает продукты с разными уровнями доступа.

Проверьте:

• владельца каталога и файлов;
• права на запись;
• происхождение каждого Skill;
• наличие вложенных скриптов;
• цели символических ссылок;
• доступ процесса к целевому пути;
• возможность подмены файла между каталогом и загрузкой.

Не принимайте внешний Skill только потому, что его имя совпадает с ожидаемым. Сверяйте содержимое, историю изменений и фактические действия. Если Skill может запускать команды, он должен проходить review почти так же строго, как скрипт автоматизации.

Отдельно разделяйте доверие к проекту и доверие к пользователю. Проектный Skill из защищённой ветки и личный Skill из домашней директории не должны автоматически считаться равнозначными. Для общего каталога используйте права только для чтения, а публикацию выполняйте через контролируемый процесс.

Используйте следующие условия:

• Если Skill зависит от структуры, команд или версии одного репозитория — выбирайте проектный уровень.
• Если Skill одинаково применим к новым и старым проектам и не использует локальные пути — выбирайте пользовательский глобальный уровень.
• Если Skill нужен нескольким сотрудникам, но проекты должны обновляться независимо — используйте общий источник и проектные зафиксированные версии.
• Если Skill доставляется в CI или удалённый execution pool — включайте его в образ, инициализацию или другой управляемый актив.
• Если проекты имеют разные доверительные границы — запрещайте общую изменяемую глобальную директорию.
• Если используется символическая ссылка — принимайте её только после проверки цели, владельца, прав и поведения наблюдателя.
• Если требуется быстрый откат — проектная копия или версия в манифесте предпочтительнее живого глобального каталога.

1. Опишите область действия. Запишите, какие проекты и пользователи должны видеть Skill. Если ответ звучит как «все», проверьте, действительно ли инструкция универсальна.

2. Выберите владельца. Для проектного Skill назначьте владельца репозитория. Для общего — команду или конкретную роль, ответственную за публикацию.

3. Создайте минимальный SKILL.md. Добавьте название, условия применения, ожидаемый результат и безопасное тестовое действие. Не начинайте с инструкций, которые изменяют файлы или запускают удалённые команды.

4. Подключите только один источник. На первом тесте не смешивайте проектный каталог, DSH_HOME и customSkillDirs. Иначе вы не поймёте, откуда пришёл найденный Skill.

5. Проверьте каталог сессии. Найдите точное имя навыка и загрузите его через модельный инструмент skill, следуя официальному описанию инструмента.

6. Измените содержимое контролируемо. Обновите описание или безопасный маркер версии. Проверьте, видит ли процесс изменение при включённом watch. Если нет — начните новую сессию.

7. Перезапустите Harness. Повторите обнаружение после остановки и запуска процесса. Для удалённой среды это обязательная часть приёмки.

8. Проверьте изоляцию. Откройте второй проект и убедитесь, что проектный Skill первого репозитория не появляется там без явного подключения.

9. Проверьте права. Временно запретите запись в общий каталог и подтвердите, что агент всё ещё может читать и загружать Skill.

10. Зафиксируйте результат. Сохраните путь, версию, владельца, дату проверки, результат перезапуска и ожидаемую область действия в документации среды.

Для удалённых Mac этот протокол стоит включать в методику приёмки облачного Mac: вместе с доступом должны проверяться не только SSH или графическая сессия, но и фактическое состояние каталогов, версия Skills и восстановление после перезапуска.

Если вы тестируете DeepSeek Harness на удалённом Mac, не переносите туда личный глобальный каталог вслепую. Это создаёт три проблемы: неизвестная версия Skill, смешение личных и командных инструкций и отсутствие доказательства, что каталог переживает перезапуск.

Для короткого эксперимента достаточно проектного каталога и отдельного тестового DSH_HOME. Для командной среды лучше доставить утверждённый общий источник только для чтения, а проектные отклонения хранить рядом с репозиторием. Перед завершением аренды сохраните манифест версий и результат проверки повторного запуска. Если нужна сама среда для такого теста, параметры размещения Mac можно сверить на странице оформления аренды Mac.

Локальный Mac удобен для постоянной разработки, но ручная настройка глобальных каталогов, различия между аккаунтами и отсутствие чистого отката делают его слабее для повторяемого эксперимента. Контейнер или обычный Linux-сервер лучше подходит для автоматизированных задач, но не всегда воспроизводит нужные macOS-инструменты и пользовательский контекст. Временная аренда Mac у KVMNODE даёт более понятную границу: вы можете подготовить отдельную среду, проверить Skills, зафиксировать версии и не менять постоянную рабочую станцию.

Если задача долгосрочная и нагрузка стабильная, выгоднее сравнить собственный Mac с арендой по сроку использования, требованиям к физическим интерфейсам и стоимости сопровождения. Но для проверки конфигурации, миграции команды или разового CI-прогона ключевым преимуществом остаётся не максимальная мощность, а чистая, повторяемая и проверяемая среда.