hns-oss-docs-i18n-rules

HARD i18n rules digest for the oss-docs harness specialists working on moai-adk-go README 4-locale set and the docs-site (adk.mo.ai.kr). Covers the canonical-locale chains, the 4-locale same-PR obligation, Mermaid TD-only, the no-emoji + icon-shortcode rule, emphasis-marker spacing, the URL blacklist, version SSOT, vercel.json redirect pattern, and the immutable Vercel binding. Loaded FIRST by every oss-docs specialist before any edit.

Quality

71%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/hns-oss-docs-i18n-rules/SKILL.md

Quality

Content

80%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a well-organized, highly actionable rules digest with concrete correct/wrong examples and exact values throughout, and clean single-file structure. Its main gap is workflow clarity: the 4-locale batch obligation externalizes validation to another skill rather than providing an inline validate→fix→retry loop.

Suggestions

Add an inline validation checkpoint for the 4-locale batch workflow (e.g., "After authoring the canonical locale, derive en/ja/zh, then run the inlined locale-parity check; if any locale is missing, fix and re-check before opening the PR") rather than only pointing to hns-oss-docs-verify.

Trim a few explanatory asides (the README-flip rationale paragraph, the sprint-contract threshold detail, the §9 "why" sentence) or move them to the SSOT doc so the digest stays minimal.

Consider a short "Workflow" section that sequences the rules into an operational order (author canonical → derive 3 locales → run parity check → add redirects if moved → never push) so the digest doubles as a checklist.

Dimension	Reasoning	Score
Conciseness	A lean rules digest that assumes Claude's competence (no explaining what i18n or Mermaid is), but a few explanatory asides — the README canonical-flip rationale paragraph, the "sprint contract locale-parity threshold 1.0, must_pass" detail, and the §9 "why" sentence — go slightly beyond minimal, keeping it at 4 rather than 5.	4 / 5
Actionability	Highly actionable throughout: concrete correct/wrong pairs ("Correct: `바이브코딩 (Vibe Coding)`… Wrong: `바이브코딩(Vibe Coding)`"), exact forbidden URL values, exact icon-shortcode syntax, and exact vercel.json redirect patterns cover the common cases — strong enough that the absence of code (it is an instruction-only skill) is not a penalty.	5 / 5
Workflow Clarity	This is a rules digest, not a sequenced workflow; the 4-locale simultaneous-update obligation is a batch operation but has no inline validate→fix→retry loop — validation is delegated out to Skill("hns-oss-docs-verify") and a parity threshold — which caps workflow clarity at 3 per the batch-operation feedback-loop rule.	3 / 5
Progressive Disclosure	A clean, well-sectioned single-file digest (9 numbered HARD-rule sections plus Known-Stale) with clearly signaled one-level-deep pointers (SSOT doc `.moai/docs/docs-site-i18n-rules.md` and the verify skill) and no nested references; appropriately self-contained for its size with easy navigation.	5 / 5
	Total	17 / 20 Passed

Description

63%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is highly concrete and distinct, comprehensively listing the rules the skill covers for a narrowly scoped project niche. Its weakness is trigger-term quality: it leans on internal harness jargon with no natural "Use when…" trigger phrasing a user would actually say.

Suggestions

Add an explicit "Use when…" clause with natural trigger phrases (e.g., "Use when editing the moai-adk-go README or docs-site content, translating between ko/en/ja/zh, or adding Mermaid diagrams, redirects, or version strings").

Include natural synonyms and surface forms users actually say ("translation", "localization", "i18n", "4-locale parity", "docs-site update") alongside the internal jargon so the skill matches natural requests.

Reframe at least one capability as a concrete action verb (e.g., "Enforces…", "Validates…", "Guides…") rather than only enumerating covered rules.

Dimension	Reasoning	Score
Specificity	Enumerates many concrete rules ("canonical-locale chains", "Mermaid TD-only", "URL blacklist", "vercel.json redirect pattern", "immutable Vercel binding") with comprehensive coverage, but these are constraints/coverage rather than explicit capability actions, with only "Loaded FIRST by every oss-docs specialist before any edit" as an action phrase — so it sits at 4 rather than 5.	4 / 5
Completeness	Has a clear "what" (HARD i18n rules digest covering the listed rules) and an explicit "when" ("Loaded FIRST by every oss-docs specialist before any edit"), but the when lacks concrete user-trigger phrases, so it does not reach 5.	4 / 5
Trigger Term Quality	Predominantly internal harness jargon ("canonical-locale chains", "version SSOT", "vercel.json redirect pattern", "immutable Vercel binding") with no natural user-facing trigger phrases or "Use when…" clause; a few recognizable terms (i18n, README, locale, docs-site) keep it above 1.	2 / 5
Distinctiveness Conflict Risk	Targets a clear narrow niche (oss-docs i18n for the moai-adk-go README 4-locale set and adk.mo.ai.kr docs-site) with distinct triggers and minimal overlap risk with other skills.	5 / 5
	Total	15 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning

	Total	15 / 16 Passed

Repository: modu-ai/moai-adk
Path: .claude/skills/hns-oss-docs-i18n-rules/SKILL.md
Commit: 4100d87

Reviewed: 2 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.