version: "1.0.1" name: xml-generation description: "MUST use WHEN нужно создать, изменить или валидировать любой XML метаданных 1С (формы, роли, объекты, MXL, СКД, EPF, расширения, конфигурация). Provides безопасную генерацию и точечную модификацию через CLI xml-gen, соблюдая правило no-manual-xml-edit." argument-hint: <domain> <operation> [<args>] allowed-tools:

• Bash
• Read
• Write
• Glob

metadata: category: 1c-development version: "2.0"

xml-generation — Toolkit для работы с XML метаданных 1С

Единый CLI xml-gen покрывает весь цикл работы с XML 1С: генерация из JSON DSL, точечная модификация существующих файлов, валидация. Этот SKILL.md — роутер: содержит обзор, индекс под-областей и сквозные принципы. За детальной спецификацией по каждому домену — переходи в соответствующий под-skill (<имя>/SKILL.md).

§1 Обзор CLI xml-gen

Установка: python tools/install.py --install-xml-gen (требует JDK 17+).

xml-gen имеет две дополняющие рабочие поверхности:

• JSON DSL surface — mxl/skd/form/role/meta compile и доступные декомпиляторы, например mxl decompile. Используй, когда артефакт удобнее описать декларативно и скомпилировать в Designer XML.
• Operational CLI surface — публичные команды epf init, epf add-template, form add-element, meta edit, template add, validate. Используй, когда нужно создать или изменить существующее дерево метаданных явными CLI-действиями.

Для сопровождения самого инструмента в xml-gen есть диагностические oracle-команды. В обычных задачах генерации/правки XML они не нужны; справочник по ним вынесен отдельно: references/behavioral-oracles.md.

Детали — в §2 и под-skills. Универсальные команды (validate, form/template/help add, edit replace-text) описаны в §3.

Не используй когда: нужен формат EDT (только Designer), нужны DataSetUnion/CalculatedFields в СКД (workaround: вычисления в запросах).

§2 Индекс под-областей

Универсальные команды (xml-gen form add, template add, help add, edit replace-text, validate) описаны в §3 ниже и не имеют отдельного под-skill-а.

§3 Универсальные команды

Четыре группы: validate (структурная/семантическая проверка любого XML), form/template/help add (добавление форм, макетов, справки к любому объекту метаданных), edit replace-text (побайтовая замена без нормализации line endings).

Когда применять: validate — перед и после каждой модификации; form/template/help add — когда нужно зарегистрировать новый артефакт без пересборки; edit replace-text — при точечной правке XML с мультилайн в <v8:content> (тултипы, описания) или любой замене, где важно сохранить line endings.

→ references/universal-commands.md

§3.1 Диагностика инструмента

Oracle-команды предназначены для сопровождения xml-gen и проверки поведения на канонических XML, а не для обычной генерации одного артефакта. Детали, режимы и тестовые матрицы см. в references/behavioral-oracles.md.

§4 Сквозные принципы

1. Формат только Designer — --format designer (default). EDT не поддерживается.
2. Encoding — UTF-8 с BOM (utf-8-sig). Сохраняй BOM при правке.
3. Line endings — CRLF между тегами, bare LF в <v8:content>. Не используй Claude Code Edit — xml-gen edit replace-text (→ references/universal-commands.md).
4. Idempotency — validate перед и после модификации. При ошибке <domain> edit делает rollback автоматически.
5. Batch operations — JSON-формат для form edit / meta edit / subsystem edit принимает массивы операций; используй вместо повторных вызовов CLI.
6. EPF layout — корневой XML: output/MyProcessor.xml. Формы EPF: output/MyProcessor/Forms/MainForm/Ext/Form.xml.
7. Oracle sandboxing — xml-gen oracle ... читает канон и пишет сгенерированные XML только под --out; не указывай oracle output внутрь src/xml.

§5 Быстрые примеры (entry-level workflows)

Создать внешнюю обработку с формой

xml-gen epf init --name MyProcessor output/
xml-gen epf add-form --epf MyProcessor --name MainForm output/
xml-gen validate --type epf output/MyProcessor

Детали — epf-full/SKILL.md.

Добавить поле на существующую форму

# 1. Изучить структуру
xml-gen form info "src/Catalogs/Контрагенты/Forms/ФормаЭлемента/Ext/Form.xml"
 
# 2. Добавить элемент с привязкой к реквизиту
xml-gen form add-element --type InputField --name Склад --path Объект.Склад \
  --parent ГруппаШапка --after Контрагент \
  "src/Catalogs/Контрагенты/Forms/ФормаЭлемента/Ext/Form.xml"
 
# 3. Проверить
xml-gen validate --type form "src/Catalogs/Контрагенты/Forms/ФормаЭлемента/Ext/Form.xml"

Детали — forms-toolkit/SKILL.md (info/edit/validate) и form-dsl/SKILL.md (compile с нуля).

Скомпилировать СКД из JSON

xml-gen skd compile schema.json Template.xml
xml-gen validate --type skd Template.xml

Детали — skd-dsl/SKILL.md. Для точечной правки готовой Schema.xml — skd-edit/SKILL.md.

Создать расширение и заимствовать объект

xml-gen extension init output_ext/ МоёРасширение --config-path output/
xml-gen extension borrow output_ext/ output/ "Catalog.Товары"
xml-gen extension diff output_ext/ output/

Детали — extension-operations/SKILL.md.

§6 Антипаттерны (правильно / неправильно)

# Неправильно: role compile с файлом на выход
xml-gen role compile role.json Roles/МояРоль.xml
 
# Правильно: output_dir → Roles/<Name>/Ext/Rights.xml
xml-gen role compile role.json output/

# Неправильно: form add-element без --path
xml-gen form add-element --type InputField --name Наименование Form.xml
 
# Правильно: --path связывает элемент с реквизитом
xml-gen form add-element --type InputField --name Наименование --path Наименование Form.xml

# Неправильно: role add-object с "view"
xml-gen role add-object --name Catalog.Номенклатура --rights view Rights.xml
 
# Правильно: права через запятую, регистр из enum RoleRight
xml-gen role add-object --name Catalog.Номенклатура --rights Read,View Rights.xml

§7 Дополнительные слои защиты (для агентов без PreToolUse)

Для агентов без PreToolUse-протокола (Codex, Cursor, Aider, Cline и др.) рекомендуется настроить дополнительные слои защиты:

• Git pre-commit hook (tools/hooks/pre-commit) — расширить вызовом --check по всем staged .xml/.mxl файлам. Это поздняя сетка: не даёт пройти в репозиторий даже если агент проигнорировал правило:

``bash python3 tools/hooks/block-direct-xml-edit.py --check "<staged-file>" --tool Edit ` При exit code 2` — файл относится к 1С metadata, коммит прерывается.

• CI на PR — тот же --check по diff отлавливает любые попытки прямой правки на входе в main.

Тонкая настройка: списки ONEC_ROOT_DIRS, EXCLUDE_SUBSTRINGS, EXCLUDE_BASENAMES задаются константами в tools/hooks/block-direct-xml-edit.py. Дополняй их, если в проекте появляется новый паттерн 1С-конфигурации (например, нестандартное расположение) или новый ложноположительный случай (build XML с уникальным именем).

§8 Workarounds

depends_on:

• framework/skills/tool-usage/platform-data/xml-generation/forms-toolkit/SKILL.md
• framework/skills/tool-usage/platform-data/xml-generation/form-dsl/SKILL.md
• framework/skills/tool-usage/platform-data/xml-generation/skd-dsl/SKILL.md
• framework/skills/tool-usage/platform-data/xml-generation/skd-edit/SKILL.md
• framework/skills/tool-usage/platform-data/xml-generation/mxl-dsl/SKILL.md
• framework/skills/tool-usage/platform-data/xml-generation/role-dsl/SKILL.md
• framework/skills/tool-usage/platform-data/xml-generation/config-operations/SKILL.md
• framework/skills/tool-usage/platform-data/xml-generation/meta-operations/SKILL.md
• framework/skills/tool-usage/platform-data/xml-generation/subsystem-interface/SKILL.md
• framework/skills/tool-usage/platform-data/xml-generation/epf-full/SKILL.md
• framework/skills/tool-usage/platform-data/xml-generation/extension-operations/SKILL.md