Converter
Convert AgentOps SKILL.md packages into Codex, Cursor, or other agent formats using a parse–convert–write pipeline and SkillBundle schema.
Overview
Converter is an agent skill most often used in Build (also Operate, Ship) that transforms AgentOps skills into target agent platforms via a SkillBundle parse–convert–write pipeline.
Install
npx skills add https://github.com/boshu2/agentops --skill converterWhat is this skill?
- Three-stage pipeline: parse → convert → write from source skill directories
- SkillBundle universal format with YAML frontmatter, body, references/, and scripts/
- CLI-style invocations: /converter skills/council codex, --all codex
- Codex target outputs SKILL.md plus prompt.md; Cursor conversion supported in quick start
- Hexagonal generic role with output_contract: converted skill files for target platform
- 3-stage pipeline: parse, convert, write
Adoption & trust: 768 installs on skills.sh; 384 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You authored skills in AgentOps format but Cursor and Codex expect different file layouts and frontmatter, so manual rewriting breaks every update.
Who is it for?
Maintainers of a shared skill repo who ship the same capabilities to Codex, Cursor, and other agents from one AgentOps source.
Skip if: Builders who only use a single vendor format with no sync need, or who want runtime MCP server deployment rather than skill file conversion.
When should I use this skill?
When converting AgentOps skill formats or running /converter for a skill path and target platform (codex, cursor, or --all).
What do I get? / Deliverables
You get converted skill files for the chosen target platform, ready to drop into that agent’s skills directory after the write stage completes.
- Converted SKILL.md (and platform extras such as prompt.md)
- SkillBundle-aligned skill tree for target agent
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Skill portability is built when you author or maintain agent capabilities and need the same logic on Claude Code, Cursor, and Codex. Agent-tooling covers cross-vendor skill packaging, reference scripts, and output contracts—not application feature code.
Where it fits
Convert a new council skill into Codex SKILL.md and prompt.md for your second IDE agent.
Run --all codex before tagging a release so external contributors get consistent skill packages.
Re-run parse–convert–write after editing references/ or scripts/ in the canonical AgentOps repo.
How it compares
Cross-platform SKILL.md packaging tool, not an in-IDE code formatter or application API client skill.
Common Questions / FAQ
Who is converter for?
Solo builders and skill maintainers using AgentOps who need repeatable exports to Codex, Cursor, and similar agents without hand-editing each platform.
When should I use converter?
Use in Build when bootstrapping a multi-agent skill library, in Ship when preparing release bundles for teammates, and in Operate when upstream SKILL.md or references/ change and targets must be regenerated.
Is converter safe to install?
It reads and writes local skill files; review the Security Audits panel on this page and run conversion in a git branch so you can diff outputs before committing.
SKILL.md
READMESKILL.md - Converter
# /converter -- Cross-Platform Skill Converter Parse AgentOps skills into a universal SkillBundle format, then convert to target agent platforms. ## Quick Start ```bash /converter skills/council codex # Convert council skill to Codex format /converter skills/vibe cursor # Convert vibe skill to Cursor format /converter --all codex # Convert all skills to Codex ``` ## 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` (Codex prompt referencing the skill). 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 rewrites known slash-skill references (for example `/plan`) to dollar-skill syntax (`$plan`), replaces Claude-specific paths/labels (including `~/.claude/`, `$HOME/.claude/`, and `/.claude/` path variants), normalizes common mixed-runtime terms (for example `Claude Native Teams`, `claude-native-teams`, and `Claude session/runtime`) to Codex-native phrasing, and rewrites Claude-only primitive labels to runtime-neutral wording. It preserves current flat `ao` CLI commands from the source skill rather than reintroducing deprecated namespace forms. It also deduplicates repeated "In Codex" runtime headings after rewrite while preserving section content. It preserves non-generated resource files/directories from the source skill (for example `templates/`, `assets/`, `schemas/`, `examples/`, `agents/`) and enforces passthrough parity (missing copied resources fail conversion). Descriptions are truncated to 1024 chars 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/converter/<target>/<skill-name>/` - **Write semantics:** Clean-write. The target directory is deleted before writing. No merge with existing content. ## 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 | |----------|-