Skill authoring guide: frontmatter placement in ja/, reserved word in claude-md name, missing TOC in long reference files

I ran the skills under 03-skills/ and its four translated copies against the authoring rules in Skill authoring best practices. Three things came up. The README tells readers to copy these directories straight into ~/.claude/skills/, so they land in real installs rather than staying on the page.

Frontmatter sits below an HTML comment in six Japanese skills

Every SKILL.md under ja/03-skills/ opens with the i18n header instead of the frontmatter delimiter:

<!-- i18n-source: 03-skills/brand-voice/SKILL.md -->
<!-- i18n-source-sha: a6380d8 -->
<!-- i18n-date: 2026-04-27 -->
---
name: brand-voice
description: ...
---

Affected files:

• ja/03-skills/blog-draft/SKILL.md
• ja/03-skills/brand-voice/SKILL.md
• ja/03-skills/claude-md/SKILL.md
• ja/03-skills/code-review-specialist/SKILL.md
• ja/03-skills/doc-generator/SKILL.md
• ja/03-skills/refactor/SKILL.md

The other 25 SKILL.md files in the repository, including the zh/, uk/ and vi/ translations of the same six skills, start with --- on line 1. Only the Japanese set carries the header, which points at the translation tooling rather than at the skills themselves.

I have not run these through a loader to reproduce a hard failure, so I am describing what I see rather than claiming a specific error. Frontmatter is read from the top of the document, and the docs say the name and description are pulled from the YAML frontmatter at startup, so a block that begins on line 4 is worth checking. Moving the three comment lines below the closing --- would settle it either way and costs nothing.

Four skills use a name the docs reserve

The name field rules say the value cannot contain the reserved words "anthropic" or "claude". These four declare name: claude-md:

• 03-skills/claude-md/SKILL.md
• vi/03-skills/claude-md/SKILL.md
• zh/03-skills/claude-md/SKILL.md
• uk/03-skills/claude-md/SKILL.md

I want to be careful here. I did not produce a load error, so what I can say is that the value conflicts with a documented constraint, not that the skill is broken. Renaming is also a breaking change, since the name is how the skill gets invoked and anyone who already installed it would have to relearn the trigger. writing-claude-md would not help because it still contains the reserved word. Something like agent-memory-file or project-context-file would clear it. Your call entirely, and leaving it as is may well be the right trade.

Twelve reference files over 100 lines have no table of contents

The docs ask for a contents list at the top of reference files longer than 100 lines, so that a partial read still shows the full scope of what the file covers. Three files are affected, once per language:

The same three under ja/, zh/ and uk/ run to within a few lines of these counts. code-smells.md opens with a title, a paragraph and a Fowler quote, then goes straight into ## Bloaters. A reader previewing the first 100 lines never learns that the Change Preventers and Dispensables groups exist further down. A short list of the ## headings at the top would fix all twelve, and it is mechanical enough to generate from the existing headings.

I opened three of these files and checked the counts by hand before writing this, and I am happy to be told any of it is wrong or not worth the churn. What brought me here was a checker I maintain that reads published skill packages against the authoring guide, so I am saying that up front rather than leaving you to wonder. My own tool double-counted the base-language files in the third section and I corrected that by hand, which is a fair signal to treat the numbers as a starting point rather than a verdict. If any of this looks useful I can send a PR for the frontmatter move and the tables of contents, both of which are safe. The rename I would leave to you. If you would rather not get this kind of report at all, tell me and I will not send another.