CRUMB a card from devarno-cloud

Skill Export Pipeline

eva intermediate 6 min read

ELI5

Once a prompt grows up to ready, eva export-skill packs it into a single SKILL.md envelope: a YAML stamp on top (name + description + version), then the <role>, <rules>, and <output_format> sections rewritten as Markdown. Drop the folder into ~/.claude/skills/ and it loads.

Technical Deep Dive

Pipeline (bin/eva:1025-1058)

flowchart TD
  call["eva export-skill <id>"] --> load["load meta.yml + prompt.xml"]
  load --> rdy{status == ready or --force?}
  rdy -- no --> die1["die: refusing to export"]
  rdy -- yes --> hasd{meta.description set?}
  hasd -- no --> die2["die: meta.description required"]
  hasd -- yes --> shape["_check_skill_export_shape"]
  shape --> probs{problems?}
  probs -->|"yes and not --force"| exit1["exit 1, list problems"]
  probs -- no --> wipe["rmtree dist/skills/<id>; mkdir"]
  wipe --> body["_xml_to_markdown(xml, meta)"]
  body --> fm["_build_skill_frontmatter(meta)"]
  fm --> write["write SKILL.md = ---\\n<fm>---\\n\\n<body>"]
  write --> done["report description chars + body words"]

SKILL.md Body Shape (bin/eva:933-1001)

_xml_to_markdown parses prompt.xml with xml.etree.ElementTree. On parse error it falls back to a fenced code block. Otherwise it extracts, in this order:

  1. <role> text → top-level paragraph after the H1 title.
  2. meta.inputs → ## Inputs bullet list ({{ name }}, required/optional, default).
  3. <rules><rule>... → ## Rules bullet list.
  4. <output_format> children → ## Output format bullet list (tag → text).
  5. Any other top-level element → its own ## <Tag> section.

Frontmatter Shape (bin/eva:1004-1022)

name: <meta.id>
description: <meta.description or meta.summary>
metadata:
  version: <meta.version>            # if set
  source_model: <meta.model>          # if set
  source: eva-hq                      # always

Output Path

dist/skills/<id>/SKILL.md — the <id> directory is wiped and recreated on every export (bin/eva:1046-1048); be careful if you placed extra files alongside the generated skill.

Key Terms

  • SKILL.md — single-file Anthropic-skills artefact: YAML frontmatter + Markdown body.
  • _check_skill_export_shape — shared shape gate used by both eva doctor and export-skill (eva-012).
  • _xml_to_markdown fallback — if prompt.xml is not valid XML, the body becomes a single fenced code block instead of structured Markdown.

Q&A

Q: What status does export-skill require by default? A: ready. Anything else dies with refusing to export status=…; pass --force to override (bin/eva:1030-1031).

Q: Which prompt.xml elements does _xml_to_markdown render specially? A: <role> (lead paragraph), <rules><rule>… (## Rules bullets), <output_format> (children become tag → text bullets); any other top-level element gets its own ## <Tag> section (bin/eva:946-998).

Q: What three keys make up the SKILL.md frontmatter metadata block? A: version (from meta.version), source_model (from meta.model if set), and source (always eva-hq) — wrapped under a top-level metadata: key (bin/eva:1010-1017).

Examples

$ eva export-skill refactor-with-constraints
exported refactor-with-constraints → dist/skills/refactor-with-constraints/SKILL.md
  description: 528 chars
  body: 412 words

neighbors on the map