1c Metadata Manage

1C Metadata Manage — Skill Dispatch

Use this skill when the task involves 1C metadata structure (creating, editing, validating, or removing configuration objects, forms, reports, layouts, roles, extensions, or databases).

Hard rule

The gate itself — every metadata-XML mutation and every infobase operation goes through this skill (dispatch below → domain doc → PowerShell tools) or the 1c-metadata-manager subagent, hand-editing is a defect, repository-bound projects add the 1c-repository-manage lock / commit discipline, EDT-format trees (.mdo / .form, never fed to these tools) route per content/rules/edt-workflow.md — is owned by AGENTS.md → Skills and Subagents; this skill's own canon is only the exceptions:

• Unambiguous one-line fix of an existing value that cannot break structure — a synonym / comment typo, a boolean flag flip on an existing element. Anything that adds / removes / reorders elements, touches UUIDs, or spans more than one line of XML is not "one-line".
• Skill not available in the session (files not installed / not exposed) — state it once in one line, then hand-edit with metadata-xml-workarounds.md loaded and validate per verification-gates.md → Gate 5.
• Read-only analysis of metadata XML is not a mutation — reading files directly is fine (subject to mcp-first-search.md for locating them).

Vendor support gate

Every mutating tool refuses to edit a locked ("на замке") object of a typical configuration on vendor support and refuses to delete one still on support — the run exits 1, the refusal is the correct outcome (extension first, support-edit only as a stated decision): support-manage.md.

Path conventions

PowerShell examples in this skill (SKILL.md and every docs/*.md) use the prefix skills/1c-metadata-manage/tools/.... That prefix is relative to the active tool's skills directory, not to the repository root:

• After installation: the script lives under <tool>/skills/1c-metadata-manage/tools/... (e.g. .cursor/skills/1c-metadata-manage/tools/..., .claude/skills/1c-metadata-manage/tools/..., .kilo/skills/1c-metadata-manage/tools/..., .ai-agent/skills/1c-metadata-manage/tools/...). Active tools that load this skill resolve the prefix automatically.
• In the 1c-rules source repository (when editing the skill itself): the same script lives under content/skills/1c-metadata-manage/tools/.... Prepend content/ when running the example outside of an installed project.

The same convention applies to docs/*.md references like skills/1c-metadata-manage/tools/1c-skd-info/modes-reference.md.

Runtime selection — Windows / Linux / macOS

Each tool of this skill ships as a PowerShell script (*.ps1). Some tools additionally ship a Python entry point (*.py) next to it, with the same parameter names and the same contract:

Exactly five commands have a Python entry point today. They are listed here by file name; these are the only shipped Python command entry points (tools/_common/dev_env.py is a shared helper, not an additional command), and no tool outside this table may be assumed to work on Linux.

Rules:

• Windows — run the .ps1 (powershell -NoProfile -File <script> …). This is the reference runtime; the PowerShell scripts are the complete toolchain.
• Linux / macOS — run the .py with python3 (python3 <script> …), same switches (-ObjectPath, -FormName, -Force, …). The ports need lxml (python3 -m pip install lxml). Installing pwsh makes the .ps1 files launchable there, but the availability of a PowerShell host does not guarantee that a Windows-specific tool works on Linux or macOS: anything that relies on COM, platform binaries, or Windows paths and encodings can still fail under pwsh. Respect the platform requirements of the individual tool instead of assuming a blanket cross-platform guarantee.
• The two runtimes are kept in parity by tests, not by convention: tools/tests/python-ports-regression.py runs both and compares the results, and CI runs the Python suite on Linux without a PowerShell host.

Upstream ships Python variants of commands that this package does not. They live in Nikolay-Shirokov/cc-1c-skills at the pinned commit ecd289fe11733028d87b55284ea9fb5feff8f513 — immutable tree: https://github.com/Nikolay-Shirokov/cc-1c-skills/tree/ecd289fe11733028d87b55284ea9fb5feff8f513/.claude/skills (for example the cf-*, cfe-* and db-* skills); attribution and local deltas: NOTICE.md. Those files are not installed and not managed by this package's manifest, and not covered by our parity tests or by the local hardening the five entry points above went through. They are therefore not a claim of full Linux / macOS support: do not install them automatically, and do not copy them over the five patched .py scripts here, which carry local fixes and would be silently overwritten. If you use one, take it from upstream deliberately, keep it outside the installed skill tree, and follow the platform instructions upstream gives for that specific tool. Their existence never makes hand-editing metadata XML acceptable.

A missing runtime does not unlock hand-editing. When a task needs a tool that has no Python entry point yet and no PowerShell host is available, that is a blocked task, not an exception to the Hard rule above — say so in one line and stop, or install pwsh. Silently hand-writing metadata XML because "the script would not run here" is the same defect as hand-editing with the tool available.

Logical addressing and optional preview

tools/_common/Invoke-1CEdit.ps1 wraps any tool of this skill and adds three things the vendored scripts do not have: a logical address instead of a physical path, a unified diff of what the run changed, and an optional preview that runs the real tool and then puts the tree back. Full reference: edit-preview.md.

Apply immediately by default. .dev.env METADATA_PREVIEW (default auto, editor /previewmode) reserves the preview for four cases: DSL generation / compilation (form-compile, meta-compile, role-compile, skd-edit batches); an object of a typical configuration while SUPPORT_GUARD is warn / off; the lock list in repository mode, on a clean tree before lock; a tool or -Operation this project has not run before. Ordinary single-field edits apply straight away.

# default: write now (logical address + unified diff after the run)
powershell -NoProfile -File skills/1c-metadata-manage/tools/_common/Invoke-1CEdit.ps1 `
    -Tool meta-edit -Object Справочник.Контрагенты `
    -Operation add-attribute -Value '{"name":"ИНН","type":"String","length":12}'

# optional: show the diff and restore the tree
powershell -NoProfile -File skills/1c-metadata-manage/tools/_common/Invoke-1CEdit.ps1 `
    -Tool meta-edit -Object Справочник.Контрагенты -Preview `
    -Operation add-attribute -Value '{"name":"ИНН","type":"String","length":12}'

• -Object <Kind>.<Name>[.Форма|Макет|Права|МодульОбъекта.<Member>] resolves to the path the tool expects and is passed as -Path. Russian and English kind names both work. This is the same address the MCP servers use for object_name, so one task no longer carries two addressing schemes. Unknown kind = a refusal listing the accepted ones, never a path that points at nothing.
• -Preview (alias -DryRun) shows the diff and restores the tree. When the tool has its own -DryRun — meta-remove, remove-form, remove-template, web-unpublish, db-load-git — that native plan is used instead, because nothing gets written that would need undoing.
• Skips in every mode, on included: a dirty watched tree (the git backend refuses), edits applied by the host's own file tools rather than a skill script (Cursor apply/reject, Claude Code rewrite — that UI is the review), and BSL rewrite_1c_code / modify_1c_code proposals, which never go through this wrapper. Do not ship a host-specific dry-run fork.
• Deletions keep their own gate. Native -DryRun then -Force on remove-form, meta-remove, remove-template, web-unpublish is unchanged. METADATA_PREVIEW does not turn those into a silent delete, and a preview is never a substitute for meta-validate / verify_xml.
• Rollback backends. A dump under git is watched whole, so a write outside the edited object is still caught and undone; the run refuses to start when the watched path already has uncommitted changes, because a rollback would take that work with it. Without git, the object folder, its parent and the root Configuration.xml are copied first, and the watched scope is printed — a write outside it is reported as unwatched rather than silently missed.
• Applying without the wrapper stays valid. Cite a preview on the Metadata tooling: line only when one actually ran.

Dispatch Strategy

Determine task complexity, then choose the execution mode:

Direct execution — simple / read-only tasks

Use when the task is a single lightweight query: checking metadata info, a quick lookup, one validation call. In this case identify the task domain from the table below, read the corresponding file, and follow its instructions directly.

Subagent delegation — complex / mutation tasks

Delegate to the 1c-metadata-manager subagent (defined in content/agents/metadata-manager.md, or in the installed agents directory for the active tool) when any of the following is true:

• The task creates, scaffolds, or compiles metadata (objects, forms, SKD, MXL, roles, EPF, CF, CFE, databases)
• The task edits multiple files or spans multiple domains
• The task involves a multi-step workflow (create → edit → validate → fix → re-validate)
• The task requires reading large domain docs (forms, meta-manage, SKD, MXL, roles, EPF, DB — each 200–800 lines)

The subagent already knows how to read the skill docs, execute PowerShell scripts, and validate results. Provide it with the full task description including object names, attributes, types, and any business context from the conversation.

Task Domain Table

If the task spans multiple domains, the subagent will read all relevant docs automatically (or read each one directly for simple tasks).