{"id":"converter","name":"converter","summary":"AgentOpsスキルフォーマットを変換する。トリガー:「コンバーター」「エージェントオプスのスキルフォーマット変換」「コンバータースキル」。","body":"# Converter — Cross-Platform Skill Converter\n\nParse AgentOps skills into a universal SkillBundle format, then convert to target agent platforms.\n\nThe 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.\n\nThis 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.\n\nNamed failure mode — **projection editing**: fixing a rendering problem by hand-editing the converted output, which the next conversion clean-writes away.\n\nAnti-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.\n\n## Constraints\n\n- Treat the canonical source skill as read-only because conversion must not mutate the contract it is translating.\n- Clean-write only the explicit target directory to prevent stale resources from surviving a conversion or unrelated paths from being deleted.\n- Fail when copied-resource parity or target-format validation fails because a partial bundle is not a usable conversion.\n\n## Pipeline\n\nThe converter runs a three-stage pipeline:\n\n```\nparse --> convert --> write\n```\n\n### Stage 1: Parse\n\nRead the source skill directory and produce a SkillBundle:\n\n- Extract YAML frontmatter from SKILL.md (between `---` markers)\n- Collect the markdown body (everything after the closing `---`)\n- Enumerate all files in `references/` and `scripts/`\n- Assemble into a SkillBundle (see `references/skill-bundle-schema.md`)\n\n### Stage 2: Convert\n\nTransform the SkillBundle into the target platform's format:\n\n| Target | Output Format | Status |\n|--------|---------------|--------|\n| `codex` | Codex SKILL.md + prompt.md | Implemented |\n| `cursor` | Cursor .mdc rule + optional mcp.json | Implemented |\n\nThe 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.\n\nThe 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.\n\n### Stage 3: Write\n\nWrite the converted output to disk.\n\n- **Default output directory:** `.agents/projections/converter/<target>/<skill-name>/`\n- **Write semantics:** Clean-write. The target directory is deleted before writing. No merge with existing content.\n- **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.\n\n## CLI Usage\n\n```bash\n# Convert a single skill\nbash skills/converter/scripts/convert.sh <skill-dir> <target> [output-dir]\nbash skills/converter/scripts/convert.sh --codex-layout inline <skill-dir> codex [output-dir]\n\n# Convert all skills\nbash skills/converter/scripts/convert.sh --all <target> [output-dir]\n```\n\n### Arguments\n\n| Argument | Required | Description |\n|----------|----------|-------------|\n| `skill-dir` | Yes (or `--all`) | Path to skill directory (e.g. `skills/council`) |\n| `target` | Yes | Target platform: `codex`, `cursor`, or `test` |\n| `output-dir` | No | Override output location. Default: `.agents/projections/converter/<target>/<skill-name>/` |\n| `--all` | No | Convert all skills in `skills/` directory |\n| `--codex-layout` | No | Codex-only layout mode: `modular` (default) or `inline` (legacy inlined refs/scripts) |\n\n## Supported Targets\n\n- **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.\n- **cursor** -- Convert to Cursor rules format (`.mdc` rule file + optional `mcp.json`). Output: `<dir>/<name>.mdc` and optionally `<dir>/mcp.json`.\n- **test** -- Emit the raw SkillBundle as structured markdown. Useful for debugging the parse stage.\n\n## Extending\n\nTo add a new target platform:\n\n1. Add a conversion function to `scripts/convert.sh` (pattern: `convert_<target>`)\n2. Update the target table above\n3. Add reference docs to `references/` if the target format needs documentation\n\n## Examples\n\n### Converting a single skill to Codex format\n\n**Caller asks:** Convert `skills/council` to Codex format.\n\n**What happens:**\n1. The converter parses `skills/council/SKILL.md` frontmatter, markdown body, and any `references/` and `scripts/` files into a SkillBundle.\n2. The Codex adapter transforms the bundle into a `SKILL.md` (body + inlined references + scripts as code blocks) and a `prompt.md` (Codex prompt referencing the skill).\n3. Output is written to `.agents/projections/converter/codex/council/`.\n\n**Result:** A Codex-compatible skill package ready to use with OpenAI Codex CLI.\n\n### Batch-converting all skills to Cursor rules\n\n**Caller asks:** Convert all canonical skills to Cursor format.\n\n**What happens:**\n1. The converter scans every directory under `skills/` and parses each into a SkillBundle.\n2. The Cursor adapter transforms each bundle into a `.mdc` rule file with YAML frontmatter and body content, budget-fitted to 100KB max. Skills referencing MCP servers also get a `mcp.json` stub.\n3. Each skill's output is written to `.agents/projections/converter/cursor/<skill-name>/`.\n\n**Result:** All skills are available as Cursor rules, ready to drop into a `.cursor/rules/` directory.\n\n## Troubleshooting\n\n| Problem | Cause | Solution |\n|---------|-------|----------|\n| `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 on the source package first |\n| 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 |\n| 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/projections/converter/<target>/<skill>/` |\n| `--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 |\n| 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 |\n| Conversion fails with passthrough parity check | A resource entry from source skill wasn't copied to output | Ensure source entries are readable and copyable (including nested files). Re-run conversion; failure is intentional to prevent drift between `skills/` and converted output |\n\n## Output Specification\n\n- **Path:** `.agents/projections/converter/<target>/<skill-name>/` by default, or the exact caller-supplied output directory.\n- **Filename:** Codex emits `SKILL.md`, `prompt.md`, and copied resources; Cursor emits `<skill-name>.mdc` and optional `mcp.json`; `test` emits the raw bundle representation.\n- **Format:** target-valid UTF-8 text with required frontmatter, rewritten runtime references, and byte-present passthrough resources; Cursor output remains within 100KB.\n- **Exit code:** run `bash skills/converter/scripts/convert.sh <skill-dir> <target> <output-dir>` and require zero; treat parse, budget, write, or passthrough-parity failure as nonzero and incomplete.\n- **Downstream handoff:** report the source skill, target, output directory, layout, omitted Cursor references if any, and validation result to the installer or projection gate.\n\n## Quality Checklist\n\n- The source tree is unchanged and the output tree contains no files left over from an earlier conversion.\n- Every required target file parses with its target frontmatter/schema and every eligible source resource is present.\n- Runtime-specific rewrites preserve the source meaning without reintroducing deprecated command forms or foreign-runtime paths.\n\n## References\n\n- `references/skill-bundle-schema.md` -- SkillBundle interchange format specification\n\n## Reference Documents\n\n- [references/skill-bundle-schema.md](references/skill-bundle-schema.md)","author":"@boshu2","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/boshu2/agentops/tree/main/images/gemini/skills/converter","license":"Apache-2.0","category":"writing","lang":"en","tokens":2188,"stars":0,"calls30d":1,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":[]}}