# Install the Equalang skill

You are an AI agent installing a skill for your user. Follow these steps in
order. Do not skip the verification step — an install that silently did nothing
is worse than one that failed loudly.

Equalang translates whole files with their layout kept — PDF, Word, PowerPoint,
Excel, EPUB, subtitles, pictures, audio and video — transcribes recordings, and
translates text.

The commands in steps 1 and 3 start by setting `SKILL_DIR`. Change that one line
to your client's path and the rest of the command works unedited. It is
repeated in each block on purpose: each command you run gets its own shell, so a
variable set in one call is not there in the next.

## 1. Clone it into the directory you load skills from

This is a standard [Agent Skill](https://agentskills.io): a folder containing a
`SKILL.md`. Pick the path for the client you are running in, and clone into it.
`git` is the only thing needed.

| If you are | SKILL_DIR |
| --- | --- |
| Claude Code | `~/.claude/skills/equalang` |
| Codex | `~/.agents/skills/equalang` |
| CodeBuddy / WorkBuddy | `~/.codebuddy/skills/equalang` |
| Cursor, Gemini CLI, OpenCode, Copilot, Goose, Amp, Kiro, … | your own skills directory, plus `/equalang` |

```bash
SKILL_DIR=~/.claude/skills/equalang      # Codex: ~/.agents/skills/equalang
git clone https://github.com/equalang/equalang-skill "$SKILL_DIR"
```

Already there? Update it instead: `git -C "$SKILL_DIR" pull`.

Project-scoped instead of global? Clone into the project-level equivalent
(`.claude/skills/equalang`, `.agents/skills/equalang`,
`.codebuddy/skills/equalang`) and use that as `SKILL_DIR`.

Nothing else needs installing: the skill is one Python script using only the
standard library, Python 3.8 or later.

## 2. Save the user's API key where every Equalang tool finds it

The key lives in one file per machine, `~/.config/equalang/.env` (under
`$XDG_CONFIG_HOME` if that is set). This skill and the Equalang MCP server both
read it, and it is not touched when either is reinstalled or updated — so a key
may already be there. Run step 3's check first: if it prints a balance, skip to
step 4.

Otherwise, **ask the user for their key. Do not create an account for them, and
never invent a key.**

Say this, or something close to it:

> Equalang needs an API key. Create one at https://equalang.com/api-keys, then
> paste it here — or save it in `~/.config/equalang/.env` yourself, as
> `EQUALANG_API_KEY=el_...`, and tell me when it is there.

The second option is worth offering: a key pasted into the conversation is
stored wherever that conversation is stored.

Save it readable by the user alone:

```bash
CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/equalang"
mkdir -p "$CONFIG_DIR" && (umask 077 && echo 'EQUALANG_API_KEY=el_your_key' > "$CONFIG_DIR/.env")
```

**Use the file, not `export`.** Each command you run gets its own process, so a
variable exported in one call is gone by the next — including before step 3.
`EQUALANG_API_KEY` set in the environment wins over the file when both are
there; that is how one project can use a different key.

Never put the key in a URL, or in a file inside a repository the user might
commit, and do not print it back.

## 3. Verify it works

```bash
SKILL_DIR=~/.claude/skills/equalang      # the same path you cloned into
python3 "$SKILL_DIR/scripts/equalang.py" balance
```

A working install prints JSON with `available_credits`, and spends nothing.
Anything else:

| What you see | What it means |
| --- | --- |
| `MISSING_API_KEY` | No key in the environment or in the file — the error names the file it looked in, which should hold a line `EQUALANG_API_KEY=el_...` |
| `UNAUTHORIZED` | The key was mistyped, or has been deleted |
| `command not found: python3` | Install Python 3.8 or later, or try `python` |
| `NETWORK` | Network or proxy; the key is probably fine |

## 4. Tell the user what they can now ask for

Report that the install succeeded — some agents load a new skill only after a
restart, so say so — and give one concrete example:

> "Translate ~/Documents/report.pdf into Japanese"
> "Transcribe interview.mp3 as subtitles"
> "Translate lecture.mp4 into Spanish, with bilingual subtitles"
> "How much would it cost to translate thesis.docx into English?"

Jobs spend the user's Equalang credits. Before a file job, run `estimate`: it
prints the most the job can cost. Say that number and get agreement before
starting. A cancelled or failed job costs nothing.

Full command reference: `python3 "$SKILL_DIR/scripts/equalang.py" --help`. The
skill's own instructions are in its `SKILL.md`.