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

# Prompt, skill, and harness commands

## Prompt management

Code-first prompt workflow — see [Prompt management](https://docs.moda.dev/prompt-management/overview.md) for concepts and [Workflow](https://docs.moda.dev/prompt-management/workflow.md) for the end-to-end guide. Running `moda prompts` with no subcommand is equivalent to `moda prompts status`.

### moda prompts init

Creates `.moda/prompts.yml` if absent (never overwrites). The default manifest is version 2: `prompt_paths` discovers `prompts/**/*.prompt.{md,json,yaml,yml}` (exact globs from the repository root), and an empty `sources: []` list holds prompts mapped in code. See [Workflow](https://docs.moda.dev/prompt-management/workflow.md#map-prompts-defined-in-code).

Paths are resolved against the current working directory, so run it from the project root. `created` distinguishes a fresh scaffold from an existing manifest, and `manifestPath` is the absolute path to verify — the agent envelope also lists it under `artifacts`.

```bash theme={"dark"}
moda prompts init
```

```json Output theme={"dark"}
{
  "manifest": ".moda/prompts.yml",
  "manifestPath": "/home/you/project/.moda/prompts.yml",
  "lockfile": ".moda/prompts.lock.json",
  "lockPath": "/home/you/project/.moda/prompts.lock.json",
  "cwd": "/home/you/project",
  "created": true,
  "promptPaths": ["prompts/**/*.prompt.md", "prompts/**/*.prompt.json", "prompts/**/*.prompt.yaml", "prompts/**/*.prompt.yml"]
}
```

If the manifest is not on disk after the run, the command exits non-zero with a `write_failed`-style error rather than reporting `status: "ok"`.

### moda prompts status / moda prompts diff

Local-only comparison of discovered prompt files against `.moda/prompts.lock.json`. No network call. `status` lists every prompt; `diff` lists only the prompts that are `changed`, `new`, or `deleted` (plus an `unchanged` count). Neither is a textual diff: the lockfile stores content hashes only. Per-prompt `state` is `new`, `changed`, `unchanged`, or `deleted`.

```bash theme={"dark"}
moda prompts status
```

```json Output (trimmed) theme={"dark"}
{
  "manifest": ".moda/prompts.yml",
  "lockfile": ".moda/prompts.lock.json",
  "manifestVersion": 2,
  "legacyManifest": false,
  "zeroMatchPatterns": [],
  "legacyOnlyFiles": [],
  "sources": 1,
  "total": 3,
  "changed": 1,
  "new": 0,
  "deleted": 0,
  "prompts": [
    { "key": "support.triage", "sourcePath": "prompts/support/triage.prompt.md", "contentHash": "b41f0c…", "lockedHash": "a92c7e…", "versionId": "pver_1f2e3d4c5b6a79880911223344556677", "state": "changed" }
  ]
}
```

`zeroMatchPatterns` lists `prompt_paths` patterns that match no file. `legacyOnlyFiles` lists `.prompt.*` files that older CLIs discovered anywhere in the repository but the current exact globs miss. When either is non-empty the command adds a warning, pointing at `moda prompts migrate` for legacy-only files.

### moda prompts migrate

Rewrites `.moda/prompts.yml` to version 2. It keeps every pattern, `sources:` entry, and comment, adds an explicit `prompt_paths` entry for each legacy-only file (so its key and lockfile entry are unchanged), and ensures a `sources:` list. The write is atomic, and a manifest that is already version 2 with nothing to add is left alone. Local-only.

```bash theme={"dark"}
moda prompts migrate --dry-run
moda prompts migrate
```

| Flag | Default | Description |
| - | - | - |
| `--dry-run` | off | Return the migrated manifest (`content`) without writing it. |
| `--discover` | off | Also scan for code-defined prompts (no agent calls). Adds only mappings that need no semantic verification; lists the rest under `pendingSources` with the command that verifies them. |

The output lists `addedPaths`, `addedSources`, `zeroMatchPatterns` (kept, reported for you to fix), and `changed`.

### moda prompts sync

Uploads all discovered prompts (unchanged ones are server-side no-ops — versions are content-addressed and immutable), moves each prompt's `current` pointer to the synced version, and writes `.moda/prompts.lock.json`.

```bash theme={"dark"}
moda prompts sync
```

```json Output (trimmed) theme={"dark"}
{
  "synced": [
    { "key": "support.triage", "promptId": "prompt_0a1b2c3d4e5f60718293a4b5", "versionId": "pver_1f2e3d4c5b6a79880911223344556677", "contentHash": "b41f0c…", "sourcePath": "prompts/support/triage.prompt.md" }
  ],
  "lockfile": ".moda/prompts.lock.json"
}
```

| Flag | Default | Description |
| - | - | - |
| `--dry-run` | off | Compute IDs without writing anything (no lockfile update). |
| `--from-harness[=<report>]` | off | First register prompt mappings from a harness report (default `.moda/harness-report.json`). Older reports are normalized; prompts that do not resolve are listed in `harnessImport.skipped` with a reason. Fails only when none resolve. |
| `--watch` | off | Poll local files and re-sync on change. |
| `--interval` | 2500 | Poll interval in ms for `--watch` (min 1,000). |

### moda prompts promote

Moves a release label (`dev`, `staging`, `prod`) to a specific version. Returns the updated prompt with all versions.

```bash theme={"dark"}
moda prompts promote support.triage --label=prod --version=pver_1f2e3d4c5b6a79880911223344556677
```

| Argument / flag | Description |
| - | - |
| `<key>` | Prompt key (required). |
| `--label` | `dev`, `staging`, or `prod` (required). |
| `--version` | Target version ID from the lockfile (`--version-id` is an alias; required). |

> [!NOTE]
>
> A `dev` promotion moves the same pointer that every sync overwrites, so it is replaced by the next `moda prompts sync`. Use `staging`/`prod` for stable release labels.

## Skills

Skill commands manage the SKILL.md files your coding agents use. `moda skills push` talks to the control plane using your API key; `moda skills install` runs offline.

### moda skills install

Copies the integration guides bundled with the CLI into `.claude/skills/<id>/` (and `.cursor/rules/<id>.mdc` when the project uses Cursor), so your own coding agent can follow them. Runs offline and never overwrites files Moda does not manage. `--list` prints every bundled guide.

`moda skills install moda-cli` installs or refreshes the CLI's own `moda-cli` skill for every detected coding agent, the same step `moda init` runs, without the rest of the wizard. Run it after upgrading the CLI so the guide matches the new version. A copy you edited locally is kept and reported as `kept`.

```bash theme={"dark"}
npm install -g @moda-ai/cli@latest && moda skills install moda-cli
moda skills install --list
moda skills install integration-node-vercel-ai-sdk
```

### moda skills push

Pushes local `.claude/skills/**/SKILL.md` files up to Moda. Files Moda manages (bundled guides installed with `moda skills install`, and the `moda-cli` skill) are skipped. `--dry-run` shows what would be pushed. `moda skills sync` and `moda sync skills` are legacy names for this command. A real sync also maintains a managed `<!-- moda:fixes:begin -->` block in the repo's `AGENTS.md` that tells coding agents to propose and make fixes themselves from Moda's evidence (`moda investigate`, `moda problems`, `moda problems get <id> --evidence`, `moda traces get`); only the fenced block is Moda-owned — the rest of the file is never touched, and `--dry-run` skips the write. If the markers are damaged (a begin marker without an end marker, an end without a begin, duplicated markers, or markers in reverse order), the file is left unchanged, `agentsMd.status` is `skipped`, and a warning explains how to repair the markers.

```bash theme={"dark"}
moda skills push --dry-run
```

## Harness

The harness commands produce and sync the cited map of your agent codebase. The supported path for analysis is the Moda GitHub App (see [Harness](https://docs.moda.dev/harness/overview.md)); the CLI analyze path is experimental.

### moda harness analyze

Produces a cited harness report. Gated: without `--experimental` or `MODA_HARNESS_ANALYZE_CLI=1` it prints a pointer to the GitHub App and exits 1.

```bash theme={"dark"}
moda harness analyze --json
```

```json Output (gated) theme={"dark"}
{
  "schema": "harness_analyze_disabled.v0.1",
  "status": "disabled",
  "reason": "cli_analyze_gated",
  "message": "Harness analysis now runs automatically via the Moda GitHub App — connect your repo in the Moda dashboard (Settings → Integrations). To run the experimental CLI analyze anyway, pass --experimental or set MODA_HARNESS_ANALYZE_CLI=1."
}
```

| Flag | Description |
| - | - |
| `--experimental` | Opt in to CLI analysis (or set `MODA_HARNESS_ANALYZE_CLI=1`). |
| `--remote` | Upload a safe source snapshot and analyze server-side (no local coding agent needed). |
| `--github-actions` | GitHub Actions OIDC mode — no Moda API key on the runner. |
| `--analyst=claude\|codex\|cursor\|local-scan` | Local analyst adapter. |
| `--yes` | Skip the read-plan approval prompt. |

### moda harness pull

Fetches a server-side analyze run (status while running, the report when done). `--sync` also syncs a passing report. `--run-id` targets a specific run; otherwise the run recorded in `.moda/harness-remote-run.json` is used.

```bash theme={"dark"}
moda harness pull --sync
```

### moda harness validate-report / approve / sync

`validate-report` checks `.moda/harness-report.json` citations. `approve --yes` validates and writes a hash-bound approval file; `sync --from-report` uploads the approved report to Moda Cloud (it refuses unapproved reports) and writes `.moda/sync-state.json`. `moda sync` and `moda sync harness` are top-level aliases for harness sync; `moda sync prompts` aliases `moda prompts sync`.

```bash theme={"dark"}
moda harness approve --yes
moda harness sync --from-report .moda/harness-report.json
```

### moda harness scan / candidates / agents / explain

Local, no-LLM inspection commands:

* `moda harness scan` — discover local runtime agents and write `.moda/harness.json` (`--json` for structured output).
* `moda harness candidates` — static candidate pre-pass with file:line citations (`--out=PATH`).
* `moda harness agents` — list detected runtime agents and families.
* `moda harness explain [--agent=<id>]` — explain the discovered harness graph.

```bash theme={"dark"}
moda harness explain --agent=agent_support
```

### moda harness delete

Permanently deletes a synced harness from Moda Cloud.

```bash theme={"dark"}
moda harness delete my-harness-key --yes
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.