converter

# Converter — Cross-Platform Skill Converter

Parse AgentOps skills into a universal SkillBundle format, then convert to target agent platforms.

The intermediate SkillBundle is what keeps conversions honest: every target reads the same parsed contract, so a rendering bug is a target-adapter bug, never a silent reinterpretation of the source. If two targets disagree about a skill's content, the bundle — not either output — arbitrates.

This is **not** the owner of the shipped `skills-codex/**` projection: that path is generated and gated by `scripts/codex-sync.sh` via `scripts/regen-all.sh`. This converter is an ad-hoc, out-of-tree exporter (Codex, Cursor) that writes under `.agents/projections/converter/`; it never mutates `skills-codex/**`. When the shipped Codex twin and this exporter disagree, the shipped path wins.

Named failure mode — **projection editing**: fixing a rendering problem by hand-editing the converted output, which the next conversion clean-writes away.

Anti-pattern: merging new output into an existing target directory to preserve local tweaks. Corrective: fix the source skill or the adapter, then re-run the clean-write conversion.

## Constraints

- Treat the canonical source skill as read-only because conversion must not mutate the contract it is translating.
- Clean-write only the explicit target directory to prevent stale resources from surviving a conversion or unrelated paths from being deleted.
- Fail when copied-resource parity or target-format validation fails because a partial bundle is not a usable conversion.

## Pipeline

The converter runs a three-stage pipeline:

```
parse --> convert --> write
```

### Stage 1: Parse

Read the source skill directory and produce a SkillBundle:

- Extract YAML frontmatter from SKILL.md (between `---` markers)
- Collect the markdown body (everything after the closing `---`)
- Enumerate all files in `references/` and `scripts/`
- Assemble into a SkillBundle (see `references/skill-bundle-schema.md`)

### Stage 2: Convert

Transform the SkillBundle into the target platform's format:

| Target | Output Format | Status |
|--------|---------------|--------|
| `codex` | Codex SKILL.md + prompt.md | Implemented |
| `cursor` | Cursor .mdc rule + optional mcp.json | Implemented |

The Codex adapter produces a `SKILL.md` with YAML frontmatter (`name`, `description`) plus rewritten body content and a `prompt.md`. Default mode is **modular**: reference docs, scripts, and resources are copied as files and `SKILL.md` includes a local resource index instead of inlining everything. Optional **inline** mode preserves the older behavior by appending inlined references and script code blocks. Codex output normalizes foreign-runtime invocation syntax and paths, rewrites unsupported primitive labels to runtime-neutral wording, and preserves current flat `ao` CLI commands. It also deduplicates repeated runtime headings while preserving section content. Non-generated resource files and directories are copied with parity checks. Descriptions are truncated to 1024 characters at a word boundary if needed.

The Cursor adapter produces a `<name>.mdc` rule file with YAML frontmatter (`description`, `globs`, `alwaysApply: false`) and body content. References are inlined into the body, scripts are included as code blocks. Output is budget-fitted to 100KB max -- references are omitted largest-first if the total exceeds the limit. If the skill references MCP servers, a `mcp.json` stub is also generated.

### Stage 3: Write

Write the converted output to disk.

- **Default output directory:** `.agents/projections/converter/<target>/<skill-name>/`
- **Write semantics:** Clean-write. The target directory is deleted before writing. No merge with existing content.
- **Refusal guard:** the write stage refuses — it does not silently redirect — when the resolved output directory equals the source package, contains it (an ancestor), or is the repository root, because the clean-write would otherwise delete the very files the conversion must read.

## CLI Usage

```bash
# Convert a single skill
bash skills/converter/scripts/convert.sh <skill-dir> <target> [output-dir]
bash skills/converter/scripts/convert.sh --codex-layout inline <skill-dir> codex [output-dir]

# Convert all skills
bash skills/converter/scripts/convert.sh --all <target> [output-dir]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `skill-dir` | Yes (or `--all`) | Path to skill directory (e.g. `skills/council`) |
| `target` | Yes | Target platform: `codex`, `cursor`, or `test` |
| `output-dir` | No | Override output location. Default: `.agents/projections/converter/<target>/<skill-name>/` |
| `--all` | No | Convert all skills in `skills/` directory |
| `--codex-layout` | No | Codex-only layout mode: `modular` (default) or `inline` (legacy inlined refs/scripts) |

## Supported Targets

- **codex** -- Convert to OpenAI Codex format (`SKILL.md` + `prompt.md`) with runtime-neutral rewrites and flat `ao` CLI preservation. Default is modular output with copied resources and a local-resource index; pass `--codex-layout inline` for legacy inlined refs/scripts. Missing copied resources fail fast.
- **cursor** -- Convert to Cursor rules format (`.mdc` rule file + optional `mcp.json`). Output: `<dir>/<name>.mdc` and optionally `<dir>/mcp.json`.
- **test** -- Emit the raw SkillBundle as structured markdown. Useful for debugging the parse stage.

## Extending

To add a new target platform:

1. Add a conversion function to `scripts/convert.sh` (pattern: `convert_<target>`)
2. Update the target table above
3. Add reference docs to `references/` if the target format needs documentation

## Examples

### Converting a single skill to Codex format

**Caller asks:** Convert `skills/council` to Codex format.

**What happens:**
1. The converter parses `skills/council/SKILL.md` frontmatter, markdown body, and any `references/` and `scripts/` files into a SkillBundle.
2. The