Skill Export Shape Gates

ELI5

Anthropic’s skills format treats certain words and shapes as reserved — like trademarked labels you can’t put on your own product. _check_skill_export_shape is the trademark office: any “claude” or “anthropic” in the id, any angle bracket in the description, or a body that grew past 5000 words gets the export blocked at the door.

Technical Deep Dive

Constants (bin/eva:280-284)

Decision Tree (bin/eva:287-326)

flowchart TD
  id["meta.id"] --> rt{contains 'claude' or 'anthropic'?}
  rt -- yes --> p1["problem: id reserved token"]
  rt -- no --> ok1
  desc["meta.description"] --> dtype{is string?}
  dtype -- no --> p2["problem: must be string"]
  dtype -- yes --> dlen{len ≤ 1024?}
  dlen -- no --> p3["problem: > 1024 chars"]
  dlen -- yes --> dchar{contains < or >?}
  dchar -- yes --> p4["problem: forbidden char"]
  dchar -- no --> dwhen{contains 'use when'?}
  dwhen -- no --> w1["warning: no trigger clause"]
  dwhen -- yes --> ok2
  trig["meta.triggers / not_for"] --> tshape{list of non-empty strings?}
  tshape -- no --> p5["problem: shape"]
  tshape -- yes --> ok3
  body["prompt.xml word count w"] --> bw{w ≥ 5000?}
  bw -- yes --> p6["problem: body too large"]
  bw -- no --> bw2{w ≥ 3500?}
  bw2 -- yes --> w2["warning: consider splitting"]
  body --> loc{non-blank lines ≥ 200?}
  loc -- yes --> w3["warning: split into references/"]

Where the gate runs

• eva doctor runs it on every prompt (bin/eva:429-431); problems fail doctor’s exit code, warnings annotate.
• eva export-skill runs it again before writing SKILL.md and refuses (exit 1) on any problem unless --force is set (bin/eva:1036-1043).

Why these limits

Reserved tokens come from Anthropic’s skill-frontmatter schema; angle brackets break YAML/HTML parsing in skill loaders; the 5000-word body cap is the “split into references/” threshold suggested by the official skills guide.

Key Terms

• reserved skill token — substring in meta.id that violates the Anthropic skill name policy; only claude and anthropic today.
• shape problem — a hard failure of the export-shape gate.
• shape warning — a soft annotation; never blocks export on its own.

Q&A

Q: Which two substrings forbid a prompt id from being exported as a skill? A: claude and anthropic — case-folded, anywhere in the id (SKILL_RESERVED_NAME_TOKENS, bin/eva:280, 293-295).

Q: Which characters are forbidden inside meta.description? A: < and >. Any occurrence triggers the problem meta.description contains '<' or '>'; forbidden in skill frontmatter (bin/eva:304-305).

Q: At what word count does prompt.xml turn from a warning into an export-blocking problem? A: 3500 words is a warning, 5000 is a problem (SKILL_BODY_WARN_WORDS / SKILL_BODY_HARD_WORDS, bin/eva:282-283, 317-321).

Examples

A description that fails the gate twice:

description: "Use this <new> claude tool for refactors."
# problems: contains '<'/'>'; (id 'claude-refactor' would also be blocked)