Does the name field's "unicode lowercase alphanumeric" wording mean to allow non-ASCII letters?

[d13mas]

docs/specification.mdx describes the name field constraint as:

May only contain unicode lowercase alphanumeric characters (a-z, 0-9) and hyphens (-)

Read literally, this is self-contradictory: it says "unicode" but the only characters given are the ASCII ranges a-z and 0-9. Every "Valid examples" / "Invalid examples" block in that section is also ASCII-only, so the doc text alone doesn't settle which reading is intended:

1. ASCII-only: "unicode" is just describing that names are matched as Unicode code points, not that non-ASCII letters are permitted. The allowed set is exactly a-z, 0-9, -.
2. Unicode letters allowed: (a-z, 0-9) are examples, not an exhaustive list — names like café-notes or 日本語-skill would be valid as long as they're lowercase.

This isn't just a hypothetical: the repo's own reference implementation (skills-ref/src/skills_ref/validator.py) has picked an answer already. Its _validate_name docstring says "Skill names support i18n characters (Unicode letters) plus hyphens," and it checks characters with Python's str.isalnum(), which accepts non-ASCII letters (and non-ASCII digits). So skills-ref currently implements reading #2, while the spec prose is genuinely ambiguous about which was intended.

Per this repo's contribution guidance, the spec is the authority here — skills-ref's behavior shouldn't be treated as the de facto answer just because it's already implemented that way. Wanted to flag it explicitly rather than have a PR quietly resolve it one way:

• If unicode letters are meant to be allowed, the spec prose should say so unambiguously (and probably needs a non-ASCII example, plus a note on normalization — e.g. is café equivalent to café (NFD)? skills-ref currently NFKC-normalizes before comparing).
• If names are meant to be ASCII-only (which is the more conservative choice, and imposes less normalization/case-folding burden on every implementing client — consistent with this project's "keep the format small" stance), then the word "unicode" should be dropped from the spec, and skills-ref's i18n support would need to be reconsidered or explicitly called out as beyond-spec leniency.

Happy to send a small follow-up PR once there's a preferred direction — this note is just to surface the ambiguity rather than resolve it unilaterally.

---

Drafted with Claude Code; reviewed by me before posting.

[mehvetero]

The spec and the reference implementation give different answers, and you caught the exact line where they diverge. Here's what I found after reading both:

The spec says ASCII-only. The parenthetical (a-z, 0-9) isn't illustrative — it's exhaustive. The sentence structure is "may only contain X characters (Y)" where Y defines X. If Unicode letters beyond a-z were intended, the parenthetical would need to say so (e.g., "Unicode letters, digits, and hyphens"). The word "unicode" in the spec reads as describing the encoding, not expanding the character set.

The reference implementation says Unicode. str.isalnum() in Python accepts é, 日, café — anything Unicode considers a letter or digit. The docstring ("i18n characters") confirms this is intentional, not accidental. It also NFKC-normalizes before comparing, which means it already handles the café vs café (NFC vs NFD) question you raised.

So which wins? Per this repo's own contribution guidance, the spec is the authority. That means:

1. If the intended answer is ASCII-only: drop "unicode" from the spec, add a note that skills-ref is lenient beyond spec. The conservative choice — every client can implement [a-z0-9-] with a trivial regex, no normalization tables needed.

2. If the intended answer is Unicode letters: change the parenthetical to something like "Unicode lowercase letters, ASCII digits 0-9, and hyphens -", add a non-ASCII example, and document the normalization form (NFKC, matching what skills-ref already does).

Either way the current text needs a one-line edit. The question is which one.

My read, for what it's worth: option 1 (ASCII-only) fits the project's "keep the format small" principle better. A name is a directory name, a URL slug, and a lookup key — all contexts where normalization surprises are expensive. But that's a judgment call, not a spec reading.

[d13mas]

Agreed on both counts — ASCII-only is the better reading of the spec text as written, and it's the one-line fix (s/unicode //) that also avoids committing every implementation to a normalization form. Since we're independently landing on the same answer, I think the actual open question is just: does that mean skills-ref's Unicode/NFKC behavior in validator.py is a bug to fix, or an intentionally-lenient superset that should get called out as beyond-spec?

Would welcome a maintainer's take on which direction a follow-up PR should take: (a) drop "unicode" from the spec prose and tighten skills-ref's _validate_name to match, or (b) keep skills-ref lenient and just document the divergence explicitly. Happy to send the PR once there's a preferred direction.

---

Drafted with Claude Code; reviewed by me before posting.

[mehvetero]

Same read. The spec fix is one deleted word — dropping "unicode" from the constraint line. If a maintainer wants to go the other way, the heavier edit (normalization form, non-ASCII examples) is well-scoped in your original post already.