Author Metadata with Claude Code

Use Claude Code with the Kodexa Metadata Skills plugin to author, edit, review, and migrate Kodexa platform configuration files in a Git-backed repository.

Claude Code is most useful when it works against real files in a metadata repository. The goal is not to generate a disconnected YAML snippet. The goal is to update the same files that kdx sync will validate and deploy.

Start From A Synced Repository

If the environment already contains resources, pull them first:

kdx sync pull --target my-org --env dev --discover --discover-dir kodexa-resources

Then commit the baseline:

git add sync-config.yaml manifests kodexa-resources .sync-state
git commit -m "Sync Kodexa metadata baseline"

Starting from a committed baseline gives Claude Code and reviewers a clean diff.

Give Claude Code The Right Scope

Open Claude Code from the repository root:

cd my-kodexa-config
claude

Start with a scoped instruction:

We are modeling invoice intake as an Activity-first Kodexa workflow.
Please inspect sync-config.yaml, manifests, and kodexa-resources.
Then propose the smallest file changes needed to add:
- an invoice data definition
- a review task template
- a review data form
- an Activity Plan that extracts, creates the review task, waits for completion,
  and calls the finance ERP service bridge after approval

Do not deploy anything. Do not create secrets. Keep changes reviewable.

This gives Claude Code the business goal, the desired Kodexa mental model, and the deployment boundary.

Ask For A Plan Before Large Edits

For non-trivial changes, ask Claude Code to describe the file plan first:

Before editing files, list the resources you will create or modify, their file paths,
and which existing resources they reference.

Review the plan for:

• resource scope: organization-level versus project-scoped
• filenames and slugs
• references to existing task templates, data forms, modules, bridges, and knowledge resources
• whether a trigger or project binding is needed
• whether the manifest needs to include new files

Useful Prompt Patterns

Create A Data Definition

Use the Kodexa data-definition skill to create a data definition for commercial invoices.
Include invoice number, invoice date, purchase order number, vendor name, currency,
subtotal, tax, total, and repeating line items. Put the file under
kodexa-resources/data-definitions/invoice.yaml and add it to the manifest.

Create A Task And Form

Create a reusable task template and V2 data form for invoice review.
The task is the human review point inside the Activity, not the process itself.
Bind the form to the invoice data definition and make the form suitable for
field correction and exception review.

Create An Activity Plan

Create an Activity Plan named invoice-intake.
It should run extraction, create an invoice review task when review is required,
wait for completion, branch on approval or rejection, and call the ERP service bridge
only after approval. Use current Activity Plan step kinds and avoid legacy planTemplate fields.

Add Knowledge-Driven Behavior

Use the knowledge-system skill to add vendor-specific extraction guidance.
Create feature and item type YAML where needed, then create a knowledge set that
applies an extraction prompt override when the vendor feature matches.

Review Existing Metadata

Review the Activity Plan, task template, data form, and project binding files for
broken references, legacy fields, missing manifest entries, and deployment risk.
Return findings with file paths and exact changes to make.

Keep References Portable

Prefer sync-friendly references over environment-specific UUIDs when the KDX sync resolver supports them.

Examples:

activityPlanRef: "activity-plan://${org}/invoice-intake"
taskTemplateRef: "${taskTemplate.invoice-review}"
dataFormRef: "${dataForm.invoice-review}"

The ${org} contract is ${org}/<slug>: the placeholder, a slash, then the resource slug. kdx sync push substitutes it with the destination organization slug in every pushed resource, including references embedded in a module’s script. If any string still contains ${org} after substitution — for example a malformed token such as ${org}-name — the push stops and reports the resource and the field paths that still carry it, instead of deploying the literal text and letting it fail later at runtime.

Portable references make the same repository usable across dev, staging, and production targets.

Review The Diff

After Claude Code edits files:

git diff

Ask Claude Code to explain the diff in Kodexa terms:

Explain this diff as a Kodexa deployment review. Focus on new resources,
references between resources, manifest changes, and risks before sync.

Avoid These Mistakes

Mistake	Better approach
Putting process orchestration inside a Task template	Create an Activity Plan and have it create or wait for Tasks
Creating one-off project-specific copies of reusable resources	Define organization-level resources and bind them into projects
Hard-coding environment UUIDs in files	Use slugs and sync reference placeholders where supported
Writing API keys or vendor credentials into YAML	Use Kodexa secrets or environment-specific secret references
Letting Claude Code deploy immediately after editing	Validate and dry-run first
Ignoring .sync-state/	Commit sync state so conflict detection works

Before You Sync

Run these checks before pushing configuration:

git diff --check
find kodexa-resources -name '*.yaml' -print0 | xargs -0 -n1 kdx validate -f
kdx sync push --target my-org --env dev --dry-run

If the dry run shows unexpected deletes, unrelated updates, or a target environment you did not intend, stop and inspect the manifest and sync configuration before pushing.