vault-administrator

Author MDL scripts, pull Vault configuration into a local workspace, manage Vault File Staging transfers, and author reports and dashboards from pulled workspace files.

Overview

For Vault administrators who need to configure, manage, and deploy Vault components. Use this plugin to author MDL scripts, pull and scope Vault configuration into a local workspace, manage Vault File Staging transfers, author reports and dashboards, and understand how components depend on each other across a Vault.

Dependencies

Plugin / Tool	Why
`vault`	VQL and data access used during configuration validation and data operations
Vault CLI (`vault`)	Pull, push (`--dry-run` for preview), and package configuration, and run MDL through the CLI when installed. Otherwise the documented Vault API is used.
Vault Documentation MCP	Answers API, MDL, VQL, and Help questions from official references.

Out of scope

Topic	Owned by
VQL query syntax and relationship traversal	`vault`
Vault Java SDK entry-point classes and Custom Pages	`vault-developer`
Environment and sandbox management (creating, refreshing, deleting sandboxes)	Vault Admin UI

Skills

Skill	Invoke with	What it does
`config`	`/vault-administrator:config`	Pull configuration into a local workspace and answer configuration questions from the workspace files.
`file-staging`	`/vault-administrator:file-staging`	Upload, download, list, delete, move, and sync files in Vault File Staging.
`mdl`	`/vault-administrator:mdl`	Create, modify, and debug Vault configuration components via MDL.
`reporting`	`/vault-administrator:reporting`	Understand, trace, clone, and draft Vault reports and dashboards from pulled workspace files.

config Skill

Pull Vault configuration into a local workspace and answer configuration questions from the workspace files.

For Vault admins, developers, and other skills that need to understand how a Vault is configured. Use this skill to pull Vault configuration into a local workspace with the Vault CLI and answer questions about objects and fields, lifecycles and workflows, picklists, and component dependencies from the workspace files.

Triggers

Explicit: "Pull my Vault's configuration", "What fields are on this object", "What depends on this picklist", "Is my workspace current", "What did we build for HR", "How does QA differ from prod".
Implicit: Another skill needs an object definition or a component's MDL before it acts. A feature has to be scoped before it is copied or packaged. The user asks whether a component exists or what references it.
Negative: Do not change configuration or run MDL. Hand off to mdl. Do not package components for another Vault. Do not answer record counts or document questions. Hand off to vault's query skill. Do not handle sign-in or credentials. Hand off to vault's login skill.

Success criteria

The skill must look for an existing workspace (a directory with .vault/state.json) in the directory the user names, then vault-config/ under the current project, and must check its __source_dns__ before trusting it. It must not search other directories for one, the home directory included, unless the user names that directory.
When no workspace for the target Vault exists, the skill must create it in the directory the user names, otherwise in vault-config/ under the current project, and must state the path in one line. It must not create one under the home directory unless the user names that directory.
If vault-config/ already holds a workspace from another Vault, the skill must ask for a directory rather than pick one.
A workspace pulled from another Vault must not be refreshed or overwritten. The pull goes to a different --dir.
The skill must not read state.json or dependencies.json whole. It searches state.json for the key it needs and walks dependencies.json with a short script.
When the user names a Vault by anything other than its full DNS, the skill must ask for the DNS rather than guess one. The CLI has no command that lists stored Vaults or credentials to resolve a label against, and the skill must not substitute another Vault.
The first time a session answers from an existing workspace, the skill must run one vault config pull --dry-run against the workspace's own source Vault and state the result. Nothing to change means current. A few changes are fixed by a pull. Most of the workspace changing means it came from an older pull. A dry run makes the same API calls as a pull, so the skill must not repeat it for each question. After that, it answers from the files and reruns the dry run only when the user asks. The check is skipped when the user pulled moments ago in the same session.
A pull dry run that returns an ERROR line for a component (Failed to fetch component <Type>.<name>: Vault did not return an MDL definition) means Vault does not return that component as MDL, not a stale workspace or a CLI fault. On a real pull that file is left as it was and the pull exits 1.
The skill must not present vault config push --dry-run as the freshness check. The preview lists a change made on the Vault since the last pull as an update the push would undo, and the freshness check is vault config pull --dry-run.
After the CLI has been upgraded, the skill must pull again before the first push, since a push from a workspace pulled with an older CLI may propose deleting components the workspace did not hold.
An answer from the workspace must quote the file path it came from. When the file is missing, the skill says which reason applies (.vdxignore, or a pull older than the component) and offers the pull that fixes it. It must not fall back to the API for a component that belongs in the workspace.
A feature's component set must come from walking .vault/dependencies.json from the seed objects in both directions, and must not come from searching names. When the seeds are not obvious, the skill asks which objects.
The walk must stop at standard (__v, __sys) components and record them as referenced. When the set grows past what the user described, the skill finds the shared custom component that joins two features, treats it as a leaf, and tells the user it is shared.
The skill must search javasdk/ and custom_pages/ for the seed object names, and must not call the set complete until the walk and that search have both run.
The scoped set must be reported grouped by component type with counts, code files listed separately, and a load order of leaves first, objects next, then what hangs off them.
The skill must not say a Vault has no code components because components/ has no folder for them. It checks through vault's query skill.
The skill must not call a feature "in use" from the presence of its components.
Without the CLI, the answer must say it came from a live call and not a workspace. A dependency question gets the single component's own references plus a note that the CLI pull is the practical way to see the whole graph.
A question about removing a field or object must be answered with the note that the files cannot show whether data is in it. The count and the inactivate-or-delete decision belong to the mdl skill.
Debug log zips, extracted logs, and trace exports go in a folder beside the workspace, never under the pulled tree.
A question about Admin > Settings must be answered by saying settings are not components and are not in the pull, and pointing at Admin > Settings in the UI.

Out of scope

Topic	Owned by
Changing configuration: MDL, and the edit and push loop	`mdl`
VPK packaging and deployment	Vault Admin UI
Record counts and document questions	`vault`'s `query` skill
Sign-in and credentials	`vault`'s `login` skill
Admin > Settings	Vault Admin UI

file-staging Skill

Upload, download, list, delete, move, rename, and sync files in Vault File Staging (VFS), including large-file resumable transfers and proof-of-upload reports.

For Vault admins and developers who need to move files to and from Vault File Staging. Use this skill to upload files (including large-file resumable transfers), download staged files, list and tidy staging areas, delete and move files, run a delta sync, and generate proof-of-upload reports.

Triggers

Explicit: "Upload this folder to file staging", "Stage these files for the load", "Download the extract from staging", "What's in my staging area", "Clean up file staging".
Implicit: Files need to reach VFS ahead of a load. A Vault-written Loader extract needs collecting. The user wants only new or changed files re-uploaded. The user wants proof a transfer landed.
Negative: Do not build the load input or submit the Vault Loader job. Hand off to api. Do not handle sign-in or classification. Hand off to vault's login skill. Do not answer questions about a file after a load has turned it into a document or record. Hand off to query. When one file is going onto one document or record, offer Direct Upload rather than defaulting to VFS.

Success criteria

Every job named in a single request is resolved ("sync this folder and give me a report" is bulk upload plus delta sync plus proof of upload). An ask that only loosely maps onto a job gets a question, not a guessed workflow.
Admin or non-Admin status is asked when unstated, never inferred, and the matching path form is used throughout. The wrong form is the most common way a drafted VFS command 404s.
Any file over 50 MB must get the full three-call resumable sequence (create session, upload parts, commit), never just the first call. A mixed-size tree branches per file rather than picking one method for the whole tree.
Bulk uploads create folders before files, parent before child. Bulk downloads list recursively first, recreate local folders from the listing, then download files, chunking anything past the Range cap into sequential requests.
Delta sync is presented as a size-and-timestamp heuristic against the current remote listing, never a content diff (the path listing carries only size and modified_date). The skill names the case it silently misses: A same-size edit with a non-newer modified date.
A proof-of-upload report claims a whole-file checksum only for a single-shot file matched against a locally computed hash. A resumable upload is marked not verifiable after the fact, since only per-part checksums exist after the transfer is over.
The target DNS and classification are stated in one line before anything is drafted or run. Upload, list, and download proceed on any Vault after the DNS is stated, but delete and move against PRODUCTION or UNKNOWN are handed over as drafted commands, never run.
Deleting a folder prompts the recursive question. Without the recursive option, deleting a non-empty folder does nothing.
An upload into an Inbox path carries the Staged-document warning: Renaming creates a new Staged document rather than renaming the existing one, and deleting the file does not delete the Staged document already created from it.
Retention is stated whenever the user asks if a file is still there: 72 hours for a Vault-written extract, one year for a user upload, and a Vault refresh clears staging entirely, with the numbers confirmed against the Vault Documentation MCP rather than quoted from memory.
Numeric API limits (burst budget, part size, concurrent sessions) are never stated from memory. The Vault Documentation MCP is named as the source.
Sign-in runs through vault's login skill. The skill never asks for a session ID or password itself.
When a staged upload feeds a downstream load, the skill stops at the staged paths and hands off to api to submit the Vault Loader job.

Out of scope

Topic	Owned by
Submitting a staged file as a Vault Loader job	`api`
A multi-object migration with dependency ordering	Migration tooling, not an admin staging job
Attaching one file straight onto one document or record	Direct Upload on that document or record's own call, not VFS
Signing in, staying signed in, production/sandbox classification	`vault`'s `login` skill
Questions about a file after a load has made it a document or record	`query`
Endpoint detail beyond the skill's own reference (request shapes, exact limits)	Vault Documentation MCP

mdl Skill

Create, modify, and debug Vault configuration components using MDL, when a change must be scripted, repeatable, or land on multiple Vaults.

For Vault administrators who need to create, modify, or debug configuration components via MDL. Use this skill when a change must be scripted, repeatable, or deployed across multiple Vaults and the Admin UI alone is not sufficient.

Triggers

Explicit: "Write an MDL statement", "Help me with MDL", "Create an object in MDL", "Alter a field with MDL", "Configure <X> in Vault".
Implicit: User needs to create or modify a Vault configuration component. User is debugging a failed MDL script. "Without using the Admin UI".
Negative: Do not trigger for VQL queries. Hand off to query. Do not trigger for Vault Java SDK source. Do not trigger for packaging components for another Vault.

Success criteria

Generated MDL must use correct syntax: Outer parentheses, semicolon terminator, comma-separated attributes, single-quoted strings and enums, unquoted booleans and numbers.
Complex attribute types (XML, JSON) must use correct syntax and schema, specific to the Component Type and attribute. High-priority examples: Pagelayout markup, Report definition and layout, Objectlifecycle rule, Objectworkflow step_detail and workflow_variables.
Report, Reporttype, and Dashboard drafts come from the reporting skill. The mdl skill executes them.
ALTER is used for targeted changes. RECREATE only when full definition replacement is the explicit goal.
Async execution is specified (not optional) when the operation meets the async-required thresholds (10,000 or more records on a raw Object with a schema-altering change).
The workspace loop is the default path for all changes, including new components. vault config push --dry-run previews the change and the second preview confirms it with no changes. Pagelayout and other XML-bodied components must go through the workspace path. vault mdl "<statement>", one statement per call, is for a change the user asks to run as a statement.
After the CLI has been upgraded, the skill must pull again before the first push, since a push from a workspace pulled with an older CLI may propose deleting components the workspace did not hold.
The skill must run the statements itself, one at a time, after the target DNS and classification are stated and the user has said go. Must not hand the user a script to run in its place.
For a component whose body is XML or split across sidecar files (a lifecycle user action, a workflow step, a page layout): the skill must start from the nearest working component of the same type in the workspace, copy it, rename it, and change only what differs. It must not retype the shape from memory, and must not send the user to the Admin UI for a change MDL supports.
A new field must start from a pulled field of the same type and keep its full attribute set. No attribute is dropped as a default.
A lifecycle user action that starts a workflow must only start the workflow. A state change must be a step inside the workflow.
When a new object is modeled on an existing one, the plan must list the configuration around the example that makes it usable (its tab or subtab, the related section on its parent's layout, its object validations) and include them unless the user says otherwise.
A new object that names a lifecycle must be authored in the same change as that lifecycle. Otherwise Vault creates an inactive placeholder lifecycle of that name.
The plan stop must come after the files are written and push --dry-run has run, so the go is given against the preview. When the request itself asked for the deploy and the target is classified non-production, that request is the go: the skill must still run the preview, must stop there only when it shows a delete or anything the planned change did not touch, and otherwise pushes and reports what the preview listed. At the plan stop the skill must give the plan's summary, list every destructive delete the plan marks, and name the known traps. A push that carries a delete is run only after the user's go for those deletes and is handed to the user to run in their own terminal, because the CLI lists the deletes and asks for confirmation that a non-interactive shell cannot give, and -y/--yes is never used in its place. Changed files are shown by path and diff, not printed whole.
Before a plan that deletes a field or an object, the skill must run one read-only count (SELECT id FROM <object> WHERE <field> != null PAGESIZE 0 for a field, SELECT id FROM <object> PAGESIZE 0 for an object) through vault api on the query endpoint, with the CLI or without it. Expect Vault to refuse a field delete while any record holds a value (OBJ-FREC-ONA-7212). The skill must not clear or migrate that data.
Before any delete of a field or object with data, the skill must say that inactivation (active(false)) keeps the data and history and can be reversed, while a delete cannot. Name which is the usual move (delete in development, inactivate to retire). Take the user's choice.
When a run stops partway, the skill must say which components are on the Vault and check the content of those that are, before continuing.
Every run step must be followed by a read-back of the changed component. vault mdl prints "MDL executed." even when nothing changed.

Out of scope

Topic	Owned by
Vault Java SDK source referenced by MDL components	`vault-developer`
Moving components between Vaults as a package	Vault UI (import package)
Record or document data queries	`query`
Submitting a prepared record load or bulk extract	`api`
Admin > Settings checkboxes	Vault Admin UI

reporting Skill

Understand, trace, clone, and draft Vault reports and dashboards from pulled workspace files.

For Vault admins who need to understand, trace, clone, or draft Vault reports and dashboards. Use this skill to read pulled Report, Reporttype, and Dashboard files, explain what a report selects, filters, groups, and joins, trace a report to its type and primary object, and draft clones or new components as MDL for the mdl skill to execute.

Triggers

Explicit: "What does this report show", "What is this report filtered on", "Which dashboards use this report", "Copy this report under a new name", "Make a report type for my custom object", "Build me a report on my custom object", "Make a dashboard from this report".
Implicit: A report or dashboard has to be understood before it is changed, dropped, or moved. A custom object needs a report type before anyone can report on it.
Negative: Do not run a report or tune a built one visually. The user runs it in Vault and does visual tweaks in the UI. Do not execute any change. Hand off to mdl. Do not answer who ran which report or read report records. Hand off to query. Do not handle who can see a report. That is Admin UI sharing rules. Do not set up scheduled or flash report delivery.

Success criteria

The skill must answer from the pulled definition.xml, layout.xml, and .mdl files and quote the paths. When there is no workspace, it hands the pull to config.
An explanation of a report must name its report type and that type's primary object, and must cover what it selects, how it filters, how it groups and sorts, and any joins on the report type.
A dependency trace must follow the report_type attribute from report to report type, primary_object from report type to object, and report="Report.<name>" from dashboard to report. Must say it is only as current as the pull.
A clone must be presented as a drafted RECREATE under a new name, started from the existing component's own files, with a checklist of what to change (name, label, report type, property paths, filters, columns, owners, viewers, editors). Execution must be handed to mdl. The skill must not write to a Vault.
The skill must not offer ALTER on a Report or offer to inactivate one. Must check for dashboards and report types that reference a report before offering a drop.
A report type for a custom object must be drafted as MDL with primary_object and, for related objects, an upRelationship or downRelationship entry, started from a report type template or an existing Standard type. The skill must say that Veeva's docs recommend the Admin UI for the XML and hand execution to mdl.
The skill must say plainly that running a report and visual tweaks are Vault UI work. Must not claim an endpoint or CLI command that runs a report.
A new report type, report, or dashboard must be drafted as RECREATE from the skill's templates. The skill must not draft CREATE or ALTER for a report, or CREATE for a dashboard. Must stop for the user's go before anything is pushed.
A built report is class('Standard') and appears under Reports. The skill does not create report views.
Before drafting a report on a custom object, the skill must check the workspace for a report type with the needed primary object and relationships. When none exists, must say so and draft the report type first through mdl, before any report.
A report definition must carry select, where, group, and order sections even when a section is empty. A tabular report must not add a bare count aggregate. A matrix report must have at least two groupings.
Every chart must name a report that is in the workspace or drafted in the same build, and group by one of that report's groupings.
After execution, the skill must read every component back. Must say plainly that a successful MDL response does not prove the report runs.
When a push comes back with the generic unknown-error response, the skill must explain it as a bad enum value, a missing report section, a missing chart attribute, or a chart count that does not fit the layout, and check them in that order.

Out of scope

Topic	Owned by
Executing a drafted change	`mdl`
Pulling or refreshing the workspace	`config`
Report records and who ran what	`query`
Who can see or edit a report	Vault Admin UI sharing rules
Running a report, visual tweaks, scheduled and flash report delivery	Vault Admin UI
Report types with more than one primary object	Vault Admin UI
Report views (`class('View')`)	Not covered