converter

name	converter
description	Convert AgentOps skill formats. Triggers: "converter", "convert agentops skill formats.", "converter skill".
practices	["refactoring","design-patterns"]
hexagonal_role	driven-adapter
consumes	[]
produces	["converted-skill"]
context_rel	[]
skill_api_version	1
context	{"window":"isolated","intent":{"mode":"none"},"sections":{"exclude":["HISTORY","INTEL","TASK"]},"intel_scope":"none"}
metadata	{"capabilities":["converter"],"effects":["write_converted_skill_projection"],"canonical_status":"canonical","disposition":"keep_specialist","tier":"cross-vendor","dependencies":[]}
output_contract	converted skill files for target platform

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