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

# Working with Claude Code

> Use Claude Code with Kodexa metadata skills to author configuration on disk, review it in Git, and sync it into Kodexa with the KDX CLI.

Kodexa configuration works best when it is treated as code: reviewed in Git, validated before deployment, and promoted through environments with the same discipline as application changes.

Claude Code can help with that workflow through the [Kodexa Metadata Skills](https://github.com/kodexa-ai/kodexa-metadata-skills) plugin. The plugin gives Claude Code resource-specific guidance for authoring Kodexa metadata on disk, including Activity Plans, task templates, data definitions, data forms, knowledge resources, project templates, modules, service bridges, prompt templates, and KDX CLI sync workflows.

<Info>
  Use this workflow when your Kodexa configuration lives in a Git repository or you want it to. For one-off operations, use the [KDX CLI resource operations](/guides/kdx-cli/resource-operations) directly.
</Info>

## The Workflow

The normal loop is:

```mermaid theme={null}
flowchart LR
  Platform["Kodexa environment"] -->|kdx sync pull| Repo["Git metadata repo"]
  Repo -->|Claude Code + Kodexa skills| Edit["Edit YAML, JSON, scripts, and modules"]
  Edit -->|review diff| PR["Pull request"]
  PR -->|kdx validate + dry run| Check["Validation"]
  Check -->|kdx sync push or deploy| Platform
```

Claude Code helps you work inside the repository. The KDX CLI is still the tool that talks to Kodexa.

## What Claude Code Should Help With

Use the skills for resource authoring, cleanup, and review:

| Work                               | Skill to use                    | Output                                                                 |
| ---------------------------------- | ------------------------------- | ---------------------------------------------------------------------- |
| Model a business process           | `activity-plan`                 | Activity Plan YAML with steps, inputs, dependencies, and actions       |
| Define human review work           | `task-template` and `data-form` | Task template YAML and V2 data form JSON                               |
| Model extracted business data      | `data-definition`               | Data definition YAML                                                   |
| Adapt behavior by document context | `knowledge-system`              | Feature types, item types, knowledge sets, and project knowledge items |
| Connect to external systems        | `service-bridge`                | Service bridge YAML for API proxy endpoints                            |
| Package custom logic               | `module`                        | Module metadata and implementation layout                              |
| Deploy and validate                | `kdx-cli`                       | Sync, validate, dry-run, push, and deploy commands                     |

For new workflow orchestration, start with **Activity Plans**. A Task is the human work item inside the process; the Activity Plan is the reusable process definition.

## What Stays In Git

A typical metadata repository includes:

```text theme={null}
my-kodexa-config/
├── sync-config.yaml
├── manifests/
│   └── finance.yaml
├── kodexa-resources/
│   ├── activity-plans/
│   ├── data-definitions/
│   ├── data-forms/
│   ├── knowledge-sets/
│   ├── modules/
│   ├── project-templates/
│   ├── projects/
│   ├── service-bridges/
│   ├── task-statuses/
│   └── task-templates/
└── .sync-state/
```

Commit the metadata files, manifests, `sync-config.yaml`, and `.sync-state/`. Do not commit API keys, secrets, generated logs, or local scratch files.

## Human Review Still Matters

Claude Code should draft and modify configuration, but a developer or platform owner should still review:

* Business meaning: Does the Activity Plan match the real process?
* References: Do task templates, forms, data definitions, modules, bridges, and knowledge sets exist in the target organization?
* Scope: Are changes limited to the intended project or reusable resource?
* Safety: Are secrets referenced by name instead of written into YAML?
* Deployment behavior: Does `kdx sync push --dry-run` or `kdx sync deploy --dry-run` show only the expected changes?

## Pages In This Section

<CardGroup cols={2}>
  <Card title="Install the Kodexa Skills" icon="plug" href="/guides/claude-code/installing-skills">
    Install the Claude Code plugin and learn how skills are invoked.
  </Card>

  <Card title="Author Metadata" icon="pen-to-square" href="/guides/claude-code/authoring-metadata">
    Use Claude Code to safely create and edit Kodexa configuration in a Git repository.
  </Card>

  <Card title="Sync with KDX" icon="arrows-rotate" href="/guides/claude-code/syncing-with-kdx">
    Pull, validate, dry-run, push, and deploy metadata with the KDX CLI.
  </Card>

  <Card title="KDX Sync Reference" icon="terminal" href="/guides/kdx-cli/sync/overview">
    Go deeper on sync configuration, manifests, conflict detection, and CI/CD.
  </Card>
</CardGroup>