Workshop Exercises

Build your Luna
localisation QA agent

Hands-on exercises for the Custom.MT workshop — create Luna, configure her soul, install her skills, and master the tools that make her great.

7 exercises 3 skills 2 hours
🚫 DO NOT USE LLMs TO TROUBLESHOOT OPENCLAW!

OPENCLAW IS TOO NEW. LLMs (ChatGPT, Claude, Gemini, etc.) do not know it. They will hallucinate commands that will break your setup.

Force LLMs consult only docs.openclaw.ai and find the right way to fix issues there based on the documentation.

🤖 Prompt for AI assistants — copy & paste
remember that when you troubleshoot openclaw you should always consult only this https://docs.openclaw.ai/ and find there the right way to fix it and not come up with your internal knowledge, when you provide an answer you reference the docs and say why to do it according to the docs
⚠️
Prerequisites — Complete Before Starting

Before you begin these exercises, please complete the Workshop Setup Guide — install Python, OpenClaw, configure OpenRouter, and run the setup validator. This takes ~10 minutes and ensures everything is ready before the session starts.

You'll build a linguistic quality scanner — an AI agent called Luna that evaluates every localised page across tone of voice, readability, accuracy, and UX. No coding background needed. Just follow the steps.

First time using Terminal?

Terminal (Mac) and PowerShell (Windows) are just text-based ways to give your computer instructions. Instead of clicking icons, you type commands and press Enter. Don't worry — we'll tell you exactly what to type.

On a Mac

  1. 1

    Press ⌘ Command + Space — this opens Spotlight Search

  2. 2

    Type Terminal and press Return (Enter)

  3. 3

    A dark window appears — that's Terminal! ✅

On Windows

  1. 1

    Press Win + R — this opens the Run dialog

  2. 2

    Type powershell and press Enter

  3. 3

    A blue window appears — that's PowerShell! ✅

How to use the commands on this page

1. Click the "Copy" button next to any command — it copies the text automatically.
2. Go to Terminal / PowerShell and right-click → Paste (or press Ctrl+V on Windows / ⌘+V on Mac).
3. Press Enter / Return — the command runs and shows you the result.

💡 What do these commands do? Every box with a dark background is a command — an instruction you give to your computer. We've added short explanations underneath each one so you always know what's happening.

01

Launch OpenClaw & Chat

Get OpenClaw running, open the Web UI, and send your first prompt.

1. Make sure OpenClaw is running. Open the browser at http://localhost:18790. If you see a chat window — you're good.

2. Copy this prompt and paste it into the chat:

Copy this prompt → paste into OpenClaw chat at localhost:18790
I need to start OpenClaw for our workshop. What commands should I run to launch the server and open the Web UI? Make the commands available for both macOS Terminal and Windows PowerShell, and explain what each does.

If OpenClaw responds in the chat — great, you're all set! Move to Step 2. If the chat doesn't respond, OpenClaw isn't running. Follow the fallback steps below.

If the chat doesn't respond at http://localhost:18790, OpenClaw isn't running. Start it with:

  1. 1

    Open Terminal (⌘+Space → type "Terminal" → Enter)

  2. 2

    Start the OpenClaw server:

    Terminal
    openclaw gateway run --bind loopback --auth none --port 18790
  3. 3

    Open http://localhost:18790 in your browser

  4. 4

    Paste the prompt above into the chat and press Enter

  1. 1

    Open PowerShell (Win+R → type "powershell" → Enter)

  2. 2

    Start the OpenClaw server:

    PowerShell
    openclaw gateway run --bind loopback --auth none --port 18790
  3. 3

    Open http://localhost:18790 in your browser

  4. 4

    Paste the prompt above into the chat and press Enter

🦞 Tip

Make sure OpenClaw is installed first. Run openclaw --version to check. If missing, install via the Workshop Setup Guide.

02

Create Workspace & Provision Luna

Copy this prompt → paste into OpenClaw chat
I need to create a workspace for my Luna localisation QA agent. Create the directory structure, placeholder files, initialise git, register Luna with the CLI, validate that Luna is registered with the CLI, and create a todo list for the remaining steps. Make sure you follow best practices of the OpenClaw agent creation: https://docs.openclaw.ai/concepts/agent-workspace

OpenClaw will complete this step for you. If you prefer to do it manually, follow the steps below.

Create Directories

Create Directories

Terminal
mkdir -p ~/.openclaw/luna-agent/{skills,docs,memory}

Create Placeholder Files

Terminal
touch ~/.openclaw/luna-agent/{AGENTS,SOUL,USER,IDENTITY,TOOLS,HEARTBEAT,BOOT,BOOTSTRAP,MEMORY}.md

Init Git & Register

  1. 1

    Init git: cd ~/.openclaw/luna-agent && git init && git add -A && git commit -m "Initial"

  2. 2

    Add Luna to AGENTS.md: Open ~/.openclaw/workspace/AGENTS.md and add:

AGENTS.md — entry to add
# Agents

## Luna
- Path: ~/.openclaw/luna-agent
- Description: Website localisation QA agent
- Soul: SOUL.md
  1. 3

    Register with CLI: openclaw agents add Luna --workspace ~/.openclaw/luna-agent --model openrouter/deepseek/deepseek-v4-pro

  2. 4

    Validate: openclaw agents list — you should see Luna in the output.

Create Directories

PowerShell
mkdir -p ~/.openclaw/luna-agent/{skills,docs,memory}

Create Placeholder Files

PowerShell
touch ~/.openclaw/luna-agent/{AGENTS,SOUL,USER,IDENTITY,TOOLS,HEARTBEAT,BOOT,BOOTSTRAP,MEMORY}.md

Init Git & Register

  1. 1

    Init git: cd ~/.openclaw/luna-agent && git init && git add -A && git commit -m "Initial"

  2. 2

    Add Luna to AGENTS.md: Open ~/.openclaw/workspace/AGENTS.md and add:

AGENTS.md — entry to add
# Agents

## Luna
- Path: ~/.openclaw/luna-agent
- Description: Website localisation QA agent
- Soul: SOUL.md
  1. 3

    Register with CLI: openclaw agents add Luna --workspace ~/.openclaw/luna-agent --model openrouter/deepseek/deepseek-v4-pro

  2. 4

    Validate: openclaw agents list — you should see Luna in the output.

📋 Note

Only create file placeholders for now. The actual content for SOUL.md, USER.md, and TOOLS.md comes in the next steps.

03

Configure Luna's SOUL.md

Set up Luna's personality — her mission, skills, rules, and constraints as a localisation QA agent.

Copy this prompt → paste into OpenClaw chat
Configure Luna's SOUL.md as follows:

Mission

Ensure every localised page reads like it was written for that locale —
not translated into it. Evaluate every surface across four dimensions:
Tone of voice, Readability, Accuracy, UX. Flag before anything ships.

Core Skills

Tone of voice: does the copy match the brand register for this
locale, or does it feel foreign?
Readability: sentence length, active voice, complexity
appropriate for web audiences in the target language
Accuracy: correct meaning, no literal translations that lose
intent, terminology consistency if glossary is present
UX: CTA urgency, character limits, label length, mobile
viewport fit per locale

Rules & Constraints

- Never edit live pages or push to any CMS
- Never flag intentional cultural adaptations as errors —
  mark as "intentional?" and ask
- Never start a review without the target locale
- If no glossary: skip terminology checks, note in report
- Always suggest an alternative when flagging
- Always check character limits before suggesting longer copy
- Escalate if source copy is ambiguous — never guess intent

Heartbeat

- On start: confirm locale, load glossary or proceed without it
- Per page: structured report (surface → dimension → severity → suggestion)
- On session end: write deviations and locale decisions to MEMORY.md

You're welcome to modify the SOUL.md file afterwards — add more rules, adjust the mission, or tailor Luna's personality to your needs.

Key Design Decisions

04

Interactive Interview

Let Luna interview you to fill in the remaining blanks in her USER.md — native language, CAT tool, working hours, and review preferences.

Copy this prompt → paste into OpenClaw chat
I want to run an interview with Luna to fill in the remaining blanks in USER.md. Tell her to ask me questions about my work and update the file with my answers.

Expected Flow

  1. 1

    Send the prompt to OpenClaw

  2. 2

    OpenClaw tells Luna to interview you

  3. 3

    Luna asks up to 5 questions (native language, CAT tool, working hours, etc.)

  4. 4

    Answer the questions — Luna updates USER.md

💡 Why

Rather than guessing or leaving placeholders, the agent asks targeted questions and fills the file itself. This builds a precise user profile without manual editing.

05

Tooling Strategy

Establish a priority system — which tool Luna should reach for first in any situation.

Copy this prompt → paste into OpenClaw chat
I need to establish Luna's tooling strategy — a priority table showing which tool to use when. Bash first, Python when bash can't handle it, browser read-only, file writes for reports only.

OpenClaw will complete this step for you. If you prefer to do it manually, use the table below.

PriorityToolWhen To UseExamples
1BashComposable, auditable, low context Character/word counts, grep, diff source vs. target, pipe text between steps
2PythonStructured analysis when bash isn't enough Readability scores (textstat), encoding checks, structured QA reports (JSON/CSV)
3BrowserFetch live pages as a user sees them Read localised pages, check hero/nav/CTA/footer rendering. Read only — no form submission.
4File WriteAtomic, irreversible — only for final output QA reports (one per page), MEMORY.md (locale decisions). Never write to source files.
⚡ Priority rule

Try Bash first. Only escalate to Python when Bash can't handle it. Browser is read-only. File writes are for reports only — never source files.

06

Configure Luna's TOOLS.md

Define what tools Luna can use — how she reads web pages, checks readability, and validates translations.

Copy this prompt → paste into OpenClaw chat
Configure Luna's TOOLS.md. She needs:

1. html-text-extract skill — to fetch and parse web pages
2. readability-check skill — to calculate Flesch scores, sentence length
3. access to bash — for grep, diff, character/word counts
4. Only read files she needs — NEVER edit live pages or CMS

Write it as a priority table showing which tool to use for which task, plus any configuration notes for each skill.
Skills

Luna's Skillset

These skills give Luna the tools to perform localisation QA — from fetching live pages to validating translations.

Install Skills
🛠

Install Skills from ClawHub

Before Luna can use external tools, install the skills she needs. First, use skill-vetter to check html-text-extract for safety, then install both.

🤖 Let OpenClaw do it

Copy this prompt → paste into OpenClaw chat
I need to install two skills for Luna: skill-vetter (security checker for skills) and html-text-extract (web page reader). First, use skill-vetter to scan html-text-extract. If it's safe, install both.

🖥️ Do it manually

Terminal
openclaw skills install skill-vetter
openclaw skills install html-text-extract
PowerShell
openclaw skills install skill-vetter
openclaw skills install html-text-extract

Install both skills. Run each command separately and wait for it to complete.

🤔 Not logged in?

Run clawhub login — it opens a browser window for authorization.

Build this Skill

Translation Validation

You don't need to write code. Just describe what you want — OpenClaw will figure out the rest. Think of it as briefing a developer who already has the right tools.

Copy this prompt → paste into OpenClaw chat
I need a tool that checks translated web pages for quality. Here's what I want it to do:

First, research the official OpenClaw documentation on skill creation — check https://docs.openclaw.ai for best practices, metadata format, and how to register skills properly.

Then, think about best practices for translation quality assurance — what do professional reviewers look for? Tone, accuracy, terminology, formatting, UI fit.

Now build a validation tool for Luna. It should work like this:

1. Take source text (English) and translated text (e.g. German) as input — use the html-text-extract skill to pull content from URLs if needed
2. Compare them side by side — flag anything that doesn't look right
3. Check for these issues specifically:
   - Meaning errors — was anything translated incorrectly?
   - Terminology problems — words that should match an approved glossary
   - Cultural adaptation — does it feel natural in the target language, not just translated?
   - Grammar and vocabulary — awkward phrasing, unnatural collocations
   - UI issues — buttons, labels, navigation that look wrong
   - Formatting — numbers, dates, currency in the wrong format
4. Always suggest a fix for every issue you flag — don't just point out problems
5. Output a clean report that I can send to a developer or translator

Store the skill in ~/.openclaw/luna-agent/skills/translation-validation/ — create a SKILL.md with proper metadata (name, description, trigger phrases) and a validation.py script.

Register the skill so Luna can see it — follow the docs for the correct registration flow.

When it's built, test it: use /skill html-extract to pull the first paragraph from https://hypefree-training.pages.dev/ai-writing, then use /skill translation-validation to translate it and validate the output.

The model will research best practices first, then build it on top of the html-extract skill you already installed.

🔍 Translation Validation

translation-validation/SKILL.md · validation.py

Systematically reviews translated web content for quality and consistency, identifies translation errors, and generates comprehensive reports with actionable corrections.

Trigger Phrases

"Check translation quality on [page]" · "Validate [section] translation" · "Review [URL] for translation errors" · "Perform localization QA on [page name]"

Error Types

CLI

Terminal
python3 validation.py \
  --source en_content.txt \
  --translated de_content.txt \
  --output report.json
🔨 How to build this skill

Create ~/.openclaw/luna-agent/skills/translation-validation/ with:

  • SKILL.md — skill definition with trigger phrases and error taxonomy
  • validation.py — Python script for side-by-side analysis and report generation
Build this Skill

Readability Check

This time, use OpenClaw's built-in Skill Creator — it guides you step by step. No need to research docs yourself.

  1. 1

    In your OpenClaw chat, type / and pick Skill Creator from the list.

  2. 2

    If Skill Creator isn't in the list, install it: type openclaw skills install skill-creator in Terminal, or just tell OpenClaw "install skill-creator from ClawHub".

  3. 3

    Once Skill Creator opens, paste the prompt below and let it build the skill for you.

Paste into Skill Creator
I need a readability checker for Luna. When I'm reviewing translated websites, I need to know if the text is too complex for the audience.

First, think about what makes text readable — what metrics do professional editors use? Flesch Reading Ease? Grade level? Sentence length?

Now build a tool that:

Takes a URL or pasted text as input — use html-text-extract if it's a URL
Runs readability metrics on the extracted text and gives me:
How easy is it to read? (Flesch Reading Ease score)
What grade level is it written at? (Flesch-Kincaid)
How many years of education do you need? (Gunning Fog)
A plain-English summary: "Grade 8 — good for general web audiences"
Warns me if the text looks like it's not English (some metrics don't work for other languages)
Warns me if the text is too short for reliable scores (under 100 words)
If the score is poor, suggest what to simplify

Store the skill in ~/.openclaw/luna-agent/skills/readability-check/ — create a SKILL.md and readability_check.py.

Validate readability of this website using the skill: https://hypefree-training.pages.dev/de/ai-writing — compare it against the English original at https://hypefree-training.pages.dev/ai-writing.
💡 What's Skill Creator?

It's OpenClaw's wizard for building skills — it handles the docs, metadata format, and registration automatically. Just describe what you want, and it builds the SKILL.md and scripts for you.

📖 Readability Check

readability-check/SKILL.md · readability_check.py

Evaluates website or text readability using Flesch, Fog, SMOG and other metrics. Flags content that is too complex for the target audience.

Trigger Phrases

"Check readability on [URL]" · "Analyze text readability" · "Evaluate [page] reading level" · "Get readability scores for [text]"

Metrics

CLI

Terminal
python3 readability_check.py --url https://example.com
python3 readability_check.py --text "Your text here"
🔨 How to build this skill

Create ~/.openclaw/luna-agent/skills/readability-check/ with:

  • SKILL.md — skill definition with trigger phrases and metrics
  • readability_check.py — Python script using textstat library for readability scoring

Requires pip install textstat.

Try It Live
🎙

Talk to Luna

Now that Luna has all her skills, put her to work. Switch to the Luna agent and ask her to evaluate a real website.

  1. 1

    Switch to Luna: In your OpenClaw chat, select the Luna agent from the agent picker, or type /luna.

  2. 2

    Ask Luna to evaluate: Paste the prompt below and let her do a full localisation QA pass on both versions of the site.

Send this to Luna
Luna, please evaluate these two websites for localisation quality:

German version: https://hypefree-training.pages.dev/de/
English original: https://hypefree-training.pages.dev/

Use all your skills — check translation accuracy, readability, terminology consistency, and UX. Give me a structured report with issues grouped by page section and severity. For each issue, include the original text, the German text, and your suggested fix.

Luna will fetch both pages, run her validation and readability tools, and produce a QA report — just like a real localisation review.

Homework

Localization Converter

A standalone skill for converting between TMX and XLIFF formats. Lives in ~/.openclaw/workspace/skills/localization-converter/.

Try building this one on your own — use the Skill Creator (/ → Skill Creator) or write the prompt yourself. The logic is straightforward: detect the input format and convert to the other one.

Paste into Skill Creator or OpenClaw chat
Build a localization file converter for Luna. It should convert between TMX (Translation Memory eXchange) and XLIFF (XML Localisation Interchange File Format) in both directions.

Requirements:
- Auto-detect the input format — if it's TMX, convert to XLIFF. If it's XLIFF, convert to TMX.
- Support TMX 1.4 and XLIFF 1.2
- Handle both single files and entire folders
- Use Python 3 standard library only — zero external dependencies
- Never modify source files
- Output a brief conversion report (files processed, direction, any issues)

Store the skill in ~/.openclaw/workspace/skills/localization-converter/ — create a SKILL.md and converter.py.

Test it with a sample TMX and XLIFF file to verify both directions work.
Standalone Skill

Localization Converter

A standalone skill for converting between TMX and XLIFF formats. Lives in ~/.openclaw/workspace/skills/localization-converter/.

🔄 TMX ↔ XLIFF Converter

Supported Formats

CLI

Terminal
# Single file
python3 converter.py input/file.tmx -o output/
python3 converter.py input/file.xliff -o output/

# Entire folder
python3 converter.py input/ -o output/

Features

The converter script is at ~/.openclaw/workspace/converter.py

Tips & Tricks

Getting the Most from OpenClaw

Practical advice — model selection, performance tuning, and routing strategies.

Use DeepSeek V4 Directly

Configure DeepSeek as a direct provider — faster, cheaper, and fewer rate limits than routing through OpenRouter.

Configuration

Terminal
openclaw config set models.providers.deepseek.apiKey "sk-your-key-here"
openclaw config set models.providers.deepseek.baseUrl "https://api.deepseek.com/v1"

Usage

Terminal
# Use the model directly (no routing)
openclaw chat --model deepseek/deepseek-v4-flash

# In gateway/webchat — prefix with provider name:
# deepseek/deepseek-chat
# deepseek/deepseek-reasoner
⚡ Why direct

Lower latency (no routing hop), fewer outages (independent of OpenRouter), full context window, and support for stream_options: {include_usage: true} for token tracking.

🧠 Switch Off Thinking

Thinking mode is great for complex reasoning but wasteful for simple tasks. Control it per-session.

Terminal
# In TUI / CLI:
openclaw chat --thinking off

# In isolated tasks (cron):
# Set payload.thinking to "disabled" or omit it
ModeBest ForAvoid When
On Complex reasoning, debugging, multi-step analysis, translation quality review Simple Q&A, formatting, boilerplate tasks
Off Fast Q&A, file operations, routine cron tasks Deep logical reasoning, multi-step validation
💡 Rule of thumb

If the task can be done in one or two sentences — thinking off. If it needs analysis, comparison, or planning — keep it on.

🔀 Use Models Directly from Provider

OpenRouter is great for exploration. For production — go direct to the provider.

Example configs
# DeepSeek
openclaw config set models.providers.deepseek.apiKey "sk-..."
openclaw config set models.providers.deepseek.baseUrl "https://api.deepseek.com/v1"

# Google / Gemini
openclaw config set models.providers.google.apiKey "..."

# OpenAI
openclaw config set models.providers.openai.apiKey "sk-..."

# Anthropic / Claude
openclaw config set models.providers.anthropic.apiKey "sk-ant-..."
AspectOpenRouterDirect Provider
Latency+50–200ms routing overheadDirect, no hop
Rate limitsShared poolYour own quota
Provider featuresLimited (no streaming metadata, limited tool-calling)Full API surface
PricingSmall markupDirect rates
Discovery✅ One key for many models❌ One key per provider
🎯 Best practice

Use OpenRouter for exploration (testing models, comparing outputs) and direct providers for production (daily workflow, cron jobs, agents). Configure both and switch with --model provider/model-name.

⚙️ Default Models & Fallbacks

Configure OpenClaw to use specific models by default and fall back gracefully when a provider is down.

Terminal
# Set the default model for all agents
openclaw config set agents.defaults.model "deepseek/deepseek-v4-flash"

# Configure fallback chain
openclaw config set agents.defaults.fallbacks \
  '["deepseek/deepseek-chat", "openai/gpt-4o"]'

# Force per-agent override
openclaw agents update Luna \
  --model deepseek/deepseek-v4-pro \
  --thinking high