converter
Cross-platform skill converter. Parse AgentOps skills into a universal bundle format, then convert to target platforms (Codex, Cursor). Triggers: convert, converter, convert skill, export skill, cross-platform.
SKILL.md
Full skill instructions
/converter -- Cross-Platform Skill Converter
Parse AgentOps skills into a universal SkillBundle format, then convert to target agent platforms.
Quick Start
/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/andscripts/ - 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 (body + inlined references + scripts as code blocks) and a prompt.md (Codex prompt referencing the skill). 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
# Convert a single skill
bash skills/converter/scripts/convert.sh <skill-dir> <target> [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/converter/<target>/<skill-name>/ |
--all | No | Convert all skills in skills/ directory |
Supported Targets
- codex -- Convert to OpenAI Codex format (SKILL.md + prompt.md). Output:
<dir>/SKILL.mdand<dir>/prompt.md. - cursor -- Convert to Cursor rules format (
.mdcrule file + optionalmcp.json). Output:<dir>/<name>.mdcand 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:
- Add a conversion function to
scripts/convert.sh(pattern:convert_<target>) - Update the target table above
- Add reference docs to
references/if the target format needs documentation
Examples
Converting a single skill to Codex format
User says: /converter skills/council codex
What happens:
- The converter parses
skills/council/SKILL.mdfrontmatter, markdown body, and anyreferences/andscripts/files into a SkillBundle. - The Codex adapter transforms the bundle into a
SKILL.md(body + inlined references + scripts as code blocks) and aprompt.md(Codex prompt referencing the skill). - Output is written to
.agents/converter/codex/council/.
Result: A Codex-compatible skill package ready to use with OpenAI Codex CLI.
Batch-converting all skills to Cursor rules
User says: /converter --all cursor
What happens:
- The converter scans every directory under
skills/and parses each into a SkillBundle. - The Cursor adapter transforms each bundle into a
.mdcrule file with YAML frontmatter and body content, budget-fitted to 100KB max. Skills referencing MCP servers also get amcp.jsonstub. - Each skill's output is written to
.agents/converter/cursor/<skill-name>/.
Result: All skills are available as Cursor rules, ready to drop into a .cursor/rules/ directory.
Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
parse error: no frontmatter found | SKILL.md is missing the --- delimited YAML frontmatter block | Add frontmatter with at least name: and description: fields, or run /heal-skill --fix on the skill first |
Cursor .mdc output is missing references | Total bundle size exceeded the 100KB budget limit | The converter omits references largest-first to fit the budget. Split large reference files or move non-essential content to external docs |
| Output directory already has old files | Previous conversion artifacts remain | This is expected -- the converter clean-writes by deleting the target directory before writing. If old files persist, manually delete .agents/converter/<target>/<skill>/ |
--all skips a skill directory | The directory has no SKILL.md file | Ensure each skill directory contains a valid SKILL.md. Run /heal-skill to detect empty directories |
Codex prompt.md description is truncated | The skill description exceeds 1024 characters | This is by design. The converter truncates at a word boundary to fit Codex limits. Shorten the description in SKILL.md frontmatter if the truncation point is awkward |
References
references/skill-bundle-schema.md-- SkillBundle interchange format specification