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

> Easily support multiple languages for the i-have-adhd skill. Learn how to add new localizations with our output formatting guide, no code changes required.

- Repository: [Ayoub Ghriss/i-have-adhd](https://github.com/ayghri/i-have-adhd)
- Tags: how-to-guide
- Published: 2026-08-05

---

**The i‑have‑adhd skill supports multiple languages through a single source of truth in [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/README.zh-CN.md) | Chinese (Simplified) |
| [`README.pt-BR.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.pt-BR.md) | Portuguese (Brazilian) |
| [`README.ja.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.ja.md) | Japanese |
| [`README.vi.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.vi.md) | Vietnamese |
| [`README.ko.md`](https://github.com/ayghri/i-have-adhd/blob/main/README.ko.md) | Korean |

Every README follows the same pattern: a brief localized introduction followed by a link to the master [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) file registers a **SessionStart** hook for Claude Code:

```json
{
  "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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml) — OpenAI function calling format
- [`skills/i-have-adhd/agents/gemini.toml`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md).

---

## Verification Across Locales

The evaluation harness ensures consistent behavior regardless of UI language.

### Running the Evaluation Script

```bash
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`](https://github.com/ayghri/i-have-adhd/blob/main/scripts/run_evals.py) injects [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/README.fr.md) to `.github/readme/`:

```markdown

# 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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) directly, bypassing the README entirely during execution.

---

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`skills/i-have-adhd/SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md) | Central rule definition with 10 formatting rules |
| `.github/readme/README.*.md` | Localized documentation linking to [`SKILL.md`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) |
| [`hooks/hooks.json`](https://github.com/ayghri/i-have-adhd/blob/main/hooks/hooks.json) | Session hook for automatic skill loading |
| [`skills/i-have-adhd/agents/openai.yaml`](https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/agents/openai.yaml) | OpenAI invocation configuration |
| [`scripts/run_evals.py`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/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`](https://github.com/ayghri/i-have-adhd/blob/main/SKILL.md) regardless of input language.