How to Support Multiple Languages with the i‑have‑adhd Skill's Output Formatting

The i‑have‑adhd skill supports multiple languages through a single source of truth in SKILL.md, allowing new localizations to be added by creating README files that reference the same language‑agnostic rule set without any code changes.

The i‑have‑adhd skill is an open-source Agent‑Skills package designed to shape LLM output for readers with ADHD. Its multilingual architecture eliminates duplication by centralizing all formatting logic in one markdown file, making supporting multiple languages with the skill's output formatting a documentation-only task.

---

Centralized Rule Architecture

The skill's multilingual support rests on a strict separation between rules and documentation. All behavioral logic lives in a single location, while language-specific files only handle user-facing explanations.

SKILL.md: The Single Source of Truth

Located at skills/i-have-adhd/SKILL.md, this file declares:

• The skill name and description
• 10 formatting rules that all language variants must follow
• Language‑agnostic markdown text that drives every localization

Because the rules are expressed as behavioral instructions rather than natural language dialogue, the same SKILL.md content works across all locales. No translation of the rule set itself is required or desired—this preserves consistent formatting behavior globally.

Localized README Files

Each supported language has a dedicated README in .github/readme/:

File	Language
README.zh-CN.md	Chinese (Simplified)
README.pt-BR.md	Portuguese (Brazilian)
README.ja.md	Japanese
README.vi.md	Vietnamese
README.ko.md	Korean

Every README follows the same pattern: a brief localized introduction followed by a link to the master SKILL.md. Translators never duplicate or modify the 10 rules.

---

Runtime Integration

The skill's runtime components are intentionally language‑blind—they inject raw rule text without inspecting locale settings.

Session Hook Registration

The hooks/hooks.json file registers a SessionStart hook for Claude Code:

{
  "hooks": [
    {
      "name": "i-have-adhd-always",
      "event": "SessionStart",
      "condition": "file_exists(\"~/.claude/.i-have-adhd-always\")",
      "action": "load_skill(\"skills/i-have-adhd/SKILL.md\")"
    }
  ]
}

The hook activates when a user creates the ~/.claude/.i-have-adhd-always flag file. The load_skill action passes the raw SKILL.md content directly to the LLM context. No language detection occurs—the same rule text applies universally.

Agent-Specific Adapters

Small configuration files tell each AI host how to invoke the skill:

• skills/i-have-adhd/agents/openai.yaml — OpenAI function calling format
• skills/i-have-adhd/agents/gemini.toml — Gemini configuration

These adapters contain no localization logic. They forward /i-have-adhd invocations unchanged to the core skill, which always reads from SKILL.md.

---

Verification Across Locales

The evaluation harness ensures consistent behavior regardless of UI language.

Running the Evaluation Script

python3 scripts/run_evals.py run \
  --runner-config evals/runners.example.json \
  --runner claude \
  --condition candidate \
  --condition-skill skills/i-have-adhd/SKILL.md \
  --output evals/results/responses.jsonl

The script at scripts/run_evals.py injects SKILL.md content as a "response-style" prompt. Since the rule file is language‑agnostic, the same validation suite confirms formatting compliance for users in any locale.

---

Adding a New Language

To support a new language, create one file. No code changes are necessary.

Step 1: Create the Localized README

Add README.fr.md to .github/readme/:

# i‑have‑adhd – Sortie adaptée aux lecteurs avec TDAH

Ce skill formatte les réponses en suivant les règles décrites dans le fichier principal :

[SKILL.md](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md)

Installez‑le avec :

```bash
agy plugin install https://github.com/ayghri/i-have-adhd

### Step 2: Verify Installation

```bash

# French UI context—the same command works universally

agy plugin install https://github.com/ayghri/i-have-adhd
/i-have-adhd

The skill activates identically because the runtime loads SKILL.md directly, bypassing the README entirely during execution.

---

Key Implementation Files

File	Purpose
skills/i-have-adhd/SKILL.md	Central rule definition with 10 formatting rules
.github/readme/README.*.md	Localized documentation linking to SKILL.md
hooks/hooks.json	Session hook for automatic skill loading
skills/i-have-adhd/agents/openai.yaml	OpenAI invocation configuration
scripts/run_evals.py	Cross-locale validation harness

---

Summary

• SKILL.md acts as the immutable source of truth for all language variants
• New languages require only a README file pointing to the master rules—no code changes
• Runtime components (hooks/hooks.json, agent adapters) are language‑agnostic by design
• The evaluation harness validates consistent formatting across all locales automatically
• This architecture scales indefinitely: adding support for any language is a documentation task, not a development task

---

Frequently Asked Questions

Does the skill automatically detect my system language?

No. The skill does not perform language detection. The same SKILL.md rules apply regardless of UI locale. Language-specific README files exist only for user onboarding convenience, not runtime behavior modification.

Why aren't the 10 rules translated?

The rules define structural formatting behaviors—bullet points, bold emphasis, line breaks—not natural language content. Translating instructions like "Use bullet points for lists" does not change the underlying behavior and risks inconsistency across locales. The rules remain in English to ensure identical execution everywhere.

Can I override rules for a specific language?

Not through the official package structure. The SKILL.md file is designed as a single source of truth. If you need localized behavioral variants, you would fork the repository and maintain a separate skill package rather than modifying the canonical i-have-adhd skill.

How do I test my new language README before submitting?

Install the skill normally and verify that /i-have-adhd produces the expected formatting. Then run the evaluation harness with your locale's test queries: python3 scripts/run_evals.py run --condition-skill skills/i-have-adhd/SKILL.md. The output should match the formatting patterns defined in SKILL.md regardless of input language.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}