md-language-check

md-language-check

When to use

Fire this skill before writing or saving any .md file under:

• src/ (source of truth — skills, rules, commands, guidelines, templates, contexts)
• dist/agent-src/ (condensed projection)
• .augment/ (local agent projection)
• agents/ (project-specific roadmaps, contexts, sessions)

Per language-and-tone § ".md files are ALWAYS English" and § Detection heuristic, every .md file in those trees must be English. Bilingual content lives only in labeled DE: … · EN: … anchor blocks.

Do NOT use when:

• Editing project content outside the trees listed above (READMEs of consumer projects, application docs that follow a different policy)
• Reviewing chat history files (agents/runtime/.agent-chat-history is JSONL, not .md)
• Inspecting non-.md files — the checker rejects them with a warning

Procedure

1. Identify the file(s) about to be saved

Collect the absolute or repo-relative path of every .md file the agent is about to create or modify in this turn. Multiple files in one turn → pass them all to a single invocation.

2. Run the checker

./scripts-run src/scripts/check_md_language <path> [<path> …] [--format json]

Exit codes:

• 0 → no German content detected, save proceeds
• 1 → violations found, save is blocked until they are resolved or explicitly suppressed
• 3 → internal error (unreadable file, decode failure)

3. Resolve findings

For every violation:

Kind	Likely cause	Fix
umlaut	German prose leaked into body text	Translate the sentence to English
de_word	German function word in unquoted prose	Translate; or move into a DE: … · EN: … block if intentional bilingual anchor

If the line is meta-documentation that must quote German tokens (e.g. the detection heuristic in language-and-tone.md itself), append <!-- md-language-check: ignore --> at the end of that single line — never as a wholesale silencer.

4. Re-run and confirm

After every fix, re-run the checker on the same paths. Save only proceeds on exit 0.

Allowed escape hatches

• Labeled anchor block — lines starting with DE: / - DE: / * DE: (and the same for EN:) are skipped automatically. Use this for intent-based opt-in / opt-out anchors.
• Fenced code blocks — \`` … ```` content is exempt, so shell snippets, JSON fixtures, and quoted user input in code blocks pass through untouched.
• Inline code — backtick spans are stripped before scanning; identifiers like für_test inside backticks do not flag.
• Per-line marker — append <!-- md-language-check: ignore --> to a line that genuinely needs to quote a German token in body prose (rare; reserved for the rules that document the heuristic).

Output format

1. One-line summary: clean or N violation(s) found
2. Per violation: file:line — kind \match`` plus the offending line
3. Next action: translate, move into a DE:/EN: block, add the per-line ignore marker, or revert the change

Gotchas

• The checker scans .md files only; passing a non-.md path emits a warning and skips it
• The detection word list is intentionally short and conservative — a clean run is necessary but not sufficient; the agent still owns the final language judgement
• Frontmatter (--- … --- at file head) is exempt; descriptions and YAML keys can use international characters where the schema allows

Do NOT

• Do NOT silence the checker by deleting trigger words from src/scripts/check_md_language.ts; extend the allow-list (anchor blocks, ignore marker) instead
• Do NOT add the ignore marker to body prose just to push a save through; the marker is for meta-documentation that quotes tokens, not a generic mute
• Do NOT skip the gate "because the file is small" — language-and-tone § Detection heuristic applies to every save under the four trees

Cloud Behavior

On cloud surfaces (Claude.ai Web, Skills API) the checker script is not shipped, so this skill is inert — the agent applies the heuristic from language-and-tone manually before emitting the file.