agent-skills-nix

Декларативное управление Agent Skills (директориями, содержащими SKILL.md) с pinning-источниками через flake, автообнаружением, выборкой, бандлингом и интеграцией с Home Manager.

Концепции

• sources: Именованные входы (flake или path), указывающие на корень скиллов (subdir). Опциональный idPrefix добавляет пространство имён к обнаруженным ID скиллов, чтобы избежать коллизий между источниками.
• discover: Рекурсивно сканирует источники на наличие директорий с SKILL.md, формируя каталог. Скиллы могут быть вложенными (например, ecosystem/c-ecosystem/), их ID используют / в качестве разделителя.
• skills.enable / skills.enableAll / skills.explicit: Декларативный выбор обнаруженных скиллов, включение всех (глобально или по списку источников) и явно заданных; автоустановка не происходит без явного согласия.
• targets: Агент-специфичные назначения, синхронизируемые из store-бандла (структуры: link, symlink-tree, copy-tree). Targets отключены по умолчанию (enable = false). Опция dest поддерживает раскрытие переменных оболочки во время выполнения (например, ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills). См. Пути targets по умолчанию ниже.

Фильтры источников

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

• idPrefix (null | string, по умолчанию: null): Префикс, добавляемый к обнаруженным ID скиллов. Полезен, когда несколько источников предоставляют одинаковые относительные пути, например idPrefix = "openai"; превращает pdf в openai/pdf.
• filter.maxDepth (null | int, по умолчанию: null): Максимальная глубина рекурсии при поиске SKILL.md. null = без ограничений (внутренний предел 100 для защиты от симлинк-петель), 1 = только непосредственные дочерние элементы, 2 = один уровень вложенности. Установите 1 для восстановления поведения без рекурсии (только плоская структура).
• filter.nameRegex (null | string, по умолчанию: null): Регулярное выражение, сопоставляемое с относительным путём скилла (например, cat-a/skill-1) для ограничения обнаружения.

Если два источника предоставляют pdf, явно задайте им префиксы для уникальности ID:

sources.openai = {
  input = "openai-skills";
  subdir = "skills";
  idPrefix = "openai";
};

sources.anthropic = {
  input = "anthropic-skills";
  subdir = "skills";
  idPrefix = "anthropic";
};

skills.enable = [ "openai/pdf" "anthropic/pdf" ];

Пути targets по умолчанию

Быстрый старт (дочерний flake + Home Manager)

Разместите конфигурацию скиллов в небольшом дочернем flake, чтобы единственными pinned-входами там были источники скиллов.

Используйте пример быстрого старта:

• Обзор: examples/quickstart/README.md
• Main (тесная связь): examples/quickstart/main/flake.nix
• Child (разделённый каталог): examples/quickstart/child/flake.nix

Примечания:

• В main agent-skills и источники скиллов перечислены непосредственно в верхнеуровневых входах.
• В child верхний уровень зависит только от skills-catalog = path:./skills; входы скиллов находятся в ./skills/flake.nix.
• Если вы используете ссылки на input источников в конфигурации модуля, передайте flake inputs в Home Manager через extraSpecialArgs.
• Чтобы включить target по умолчанию, установите targets.<name>.enable = true; (например, targets.claude.enable = true;).
• structure = "link" использует симлинки home.file; symlink-tree и copy-tree выполняются в home.activation.
• symlink-tree использует rsync -a --delete (сохранение симлинков); copy-tree использует rsync -aL --delete (разыменование симлинков).
• dest поддерживает раскрытие переменных оболочки во время выполнения (например, ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills). Примечание: структура link не поддерживает переменные оболочки и будет использовать fallback-путь.

Выходные данные flake

• packages.<system>.agent-skills-bundle: Store-бандл выбранных скиллов (пустой по умолчанию; настраивается в потребителях).
• apps.<system>.skills-install: Синхронизирует бандл с включёнными глобальными targets (см. Пути targets по умолчанию). Переопределите назначения через AGENT_SKILLS_DESTS.
• apps.<system>.skills-install-local: Синхронизирует бандл с включёнными локальными targets (см. Пути targets по умолчанию) с использованием copy-tree. Переопределите корень через AGENT_SKILLS_ROOT, назначения через AGENT_SKILLS_LOCAL_DESTS.
• apps.<system>.skills-list: JSON-представление каталога по умолчанию.
• checks.<system>.skills: Проверка корректности сборки бандла.
• homeManagerModules.default: Модуль Home Manager, реализующий описанный DSL.
• lib.agent-skills: Вспомогательные функции (discoverCatalog, selectSkills, mkBundle, mkLocalInstallScript, mkShellHook, catalogJson, defaultConfig).

Библиотечные функции

См. examples/library-functions/snippet.nix.

discoverCatalog рекурсивно обнаруживает директории с SKILL.md и генерирует ID с разделителем / для вложенных скиллов (например, cat-a/skill-1). Установите idPrefix на источнике для добавления пространства имён к обнаруженным ID (например, openai/pdf). Функция проверяет наличие SKILL.md и отклоняет дублирующиеся ID после добавления префикса (сообщения об ошибках включают абсолютные пути обоих конфликтующих источников). selectSkills выдаёт ошибку при наличии неизвестных записей в allowlist или отсутствующих файлов, предотвращая случайное расхождение. (Home Manager отображает skills.enable → allowlist и skills.explicit → skills.)

Кастомизация скиллов

Явные скиллы поддерживают опции transform и packages для настройки SKILL.md и зависимостей бандла:

См. examples/skill-customization/explicit-transform.nix.

Это генерирует: