ATBX Direct Editor

Version: v0.1.0

Treat every .atbx edit as a tool contract change across several archive members. A successful edit keeps structure, localized text, metadata, validation logic, execution logic, and package integrity in parity.

Quality Bar

Use these five gates throughout the task:

• Trust: Base claims on inspected archive contents. Label uncertain conclusions as Confirmed, Inferred, or Unverified; never invent missing ArcGIS/GeoScene semantics.
• Reliability: Prefer bundled scripts for archive IO, metadata regeneration, validation, backups, and reports. Fail closed when any required layer cannot be updated or verified.
• Adaptability: Choose the narrowest safe path for the actual archive shape: manifest-driven edits for explicit parameter changes, focused validation for touched tools, manual review for opaque scripts or unusual package layouts.
• Convention: Preserve .atbx archive conventions: forward-slash entry names, no duplicate ZIP entries, UTF-8 XML, UTF-8 JSON with ASCII escaping for non-ASCII text, and $rc: indirection through .rc maps.
• Effectiveness: Change only the files needed to satisfy the user request, regenerate derived metadata, validate the result, and report residual risk rather than hiding it.

Core Rules

• Use this skill only for archived .atbx files that can be opened as ZIP packages.
• If the target is an expanded directory rather than an archive file, treat it as a normal folder edit and do not use archive repack scripts.
• Treat .tool/tool.content as the authoritative parameter structure.
• Treat .tool/tool.content.rc as the authoritative localized text source when tool.content uses $rc:....
• Treat .tool/tool.metadata.xml as a required synchronized projection, not optional documentation.
• Treat tool.script.validate.py and tool.script.execute.py as part of the same parameter contract whenever parameters, value lists, indexes, defaults, or allowed values change.
• Do not claim success after changing only one layer of the contract.

Mandatory Workflow

1. Run scripts/inspect_atbx.py before editing.
2. Read references/atbx-format-notes.md and references/known-file-patterns.md only when package shape, file roles, or edit targets are unclear.
3. Build the intended tool contract before editing:
• parameter order, names, display labels, rc keys, defaults, value lists/domains
• validate/execute parameter index usage and downstream argument packing
• metadata parameter list, summary, and help text
4. Pick the edit path:
• Use scripts/apply_parameter_changes.py for clear, repeatable parameter changes described by a manifest.
• Use scripts/patch_atbx.py only for tightly scoped deterministic changes.
• Use manual archive inspection/editing only when scripts cannot express the change safely.
5. Edit real sources first: tool.content, tool.content.rc, tool.script.validate.py, and tool.script.execute.py as required.
6. Run scripts/sync_tool_metadata.py for every edited tool unless apply_parameter_changes.py already regenerated metadata.
7. Run scripts/validate_atbx.py on the edited archive. Use --tool ToolName for focused checks when unrelated historical defects exist outside the changed tools.
8. Use references/validation-checklist.md before final delivery.
9. Report what changed, what was synchronized, what was validated, and what remains uncertain.

Environment Guardrails

• Run scripts from the skill directory or pass paths that make scripts/atbxlib importable.
• On GeoScene workstations, clear PYTHONHOME and PYTHONPATH for helper-script processes when the default Python is polluted.
• If Python fails before script startup, for example ModuleNotFoundError: No module named 'encodings', switch to a known-good Python executable or report that script validation could not run.
• If a helper reads UTF-8 files through locale defaults, set PYTHONUTF8=1 for that process.
• Prefer the GeoScene/ArcGIS Python executable only when it is the stable, complete runtime needed by the local machine.

Encoding And Repack Rules

• Read archive text through bundled Python helpers instead of shell-default decoding.
• Do not treat mojibake from PowerShell or a terminal as evidence that archive payloads are damaged.
• Write .content and .rc JSON as UTF-8 with ASCII escaping for non-ASCII text.
• Write XML as UTF-8.
• Repack archives with normalized forward-slash entry names.
• Treat duplicate ZIP entry names as a failure.
• Create a backup before any in-place edit.

Parameter Contract Rules

For any add, remove, rename, reorder, type change, default change, or value-list edit, verify all of:

• tool.content parameter list and order
• tool.content.rc labels, descriptions, and enum labels
• tool.metadata.xml parameter list, order, summary, and help text
• tool.script.validate.py index usage, enable/disable logic, filters, and messages
• tool.script.execute.py index usage, branches, conversions, and downstream calls

High-risk patterns:

• Numeric parameter indexes in validate/execute scripts after a reorder.
• Range toggles such as range(4, 16) after adding or removing parameters.
• Value lists whose displayed labels live in rc entries or metadata.
• Opaque, encoded, or hex-like script payloads. Preserve these unless the user explicitly accepts experimental script changes.
• New parameters that execution cannot consume yet. Report the tool as incomplete instead of done.

Metadata Synchronization

Always synchronize tool.metadata.xml after parameter or text edits. Do not assume ArcGIS Pro or GeoScene ignores metadata.

Use:

python scripts/sync_tool_metadata.py path/to/file.atbx --tool ToolName --output path/to/out.atbx

Use --in-place only when the user explicitly wants the source archive rewritten and a backup is acceptable.

The metadata sync helper:

• rebuilds tool.metadata.xml from tool.content
• resolves display text through tool.content.rc
• preserves existing metadata descriptions where possible
• backfills missing rc description keys from old metadata when rc entries are absent
• regenerates parameter lists so metadata names, count, and order match tool.content

Script Entry Points

• scripts/inspect_atbx.py: inventory, structure, and initial validation.
• scripts/diff_atbx.py: compare before/after archives by normalized internal path.
• scripts/apply_parameter_changes.py: default entry point for manifest-driven parameter edits.
• scripts/patch_atbx.py: narrowly scoped deterministic patches.
• scripts/sync_tool_metadata.py: regenerate metadata after source changes.
• scripts/validate_atbx.py: final archive and contract validation.

Manifest-driven example:

python scripts/apply_parameter_changes.py path/to/file.atbx \
  --manifest references/parameter-change-manifest.example.json \
  --output path/to/out.atbx

Supported manifest operation kinds:

• set-tool-fields
• rc-set
• set-parameter-domain
• add-parameter
• remove-parameter
• rename-parameter
• update-parameter
• reorder-parameters
• script-replace-text
• script-replace-regex

The manifest helper applies content and rc changes, refuses structural parameter edits unless validate/execute changes are covered or assume_scripts_already_aligned=true, regenerates metadata, and runs focused validation.

See references/parameter-change-manifest.example.json when constructing a manifest.

Do Not Do These

• Do not edit only tool.metadata.xml and skip tool.content.
• Do not edit only tool.content and skip metadata sync.
• Do not trust shell-decoded text when Chinese labels look garbled.
• Do not repack with backslash entry names.
• Do not declare success because the .atbx still opens as a ZIP.
• Do not use this skill for .tbx, .pyt, unrelated ArcPy scripting, or read-only license/version audits.

Delivery Format

Report:

1. target archive and tools
2. edit path used: manifest, deterministic patch, or manual
3. changed internal files
4. parameter contract changes
5. metadata sync result
6. validation result
7. quality-gate status for Trust, Reliability, Adaptability, Convention, and Effectiveness
8. residual risks or unresolved dynamic references