> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
kdx sync pull --target my-org --env dev --discover --discover-dir kodexa-resources
```

Then commit the baseline:

```bash theme={null}
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:

```bash theme={null}
cd my-kodexa-config
claude
```

Start with a scoped instruction:

```text theme={null}
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:

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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:

```yaml theme={null}
activityPlanRef: "activity-plan://${org}/invoice-intake"
taskTemplateRef: "${taskTemplate.invoice-review}"
dataFormRef: "${dataForm.invoice-review}"
```

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

## Review The Diff

After Claude Code edits files:

```bash theme={null}
git diff
```

Ask Claude Code to explain the diff in Kodexa terms:

```text theme={null}
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:

```bash theme={null}
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.