# Install and update

> Where the rd-* skills go for Claude Code and Codex, global versus per-repo, and what to do when one does not show up.

Both clients load skills from a directory. Installing is copying files into it.
The CLI does that, verifies each file against a published hash, and records what
it wrote so it can update or remove exactly those files later.

## Claude Code

<steps>

<step title="Install the CLI, if you have not">

```bash
npm install -g radial.build
```

Homebrew works too: `brew install BrainGridAI/radial/radial`.

</step>

<step title="Install the pack">

```bash
radial skills install --agent claude
```

Files land in `~/.claude/skills/rd-*`. Leave off `--agent` to install for every
client the CLI can see on this machine.

</step>

<step title="Restart Claude Code">

Both clients read the skills directory at startup, so a running session will not
see a skill that appeared underneath it.

</step>

<step title="Check">

Type `/rd-` and the eleven names should complete. `radial skills list` shows the
same thing from the terminal, with an arrow beside anything out of date.

</step>

</steps>

## Codex

<steps>

<step title="Install the pack">

```bash
radial skills install --agent codex
```

Files land in `~/.agents/skills/rd-*`. If this machine's Codex reads
`$CODEX_HOME/skills` instead (older builds default that to `~/.codex/skills`),
the installer detects it and writes there, recording the directory it chose in
the lock so `update` and `remove` go to the same place.

</step>

<step title="Restart Codex, then invoke a skill">

Type `$rd-setup`. `radial skills list` shows the same set from the terminal.

</step>

</steps>

## Global or per-repo

Global is the default and is usually right: the skills are generic, and you want
them wherever you work.

`--project` writes into `.claude/skills` and `.agents/skills` under the current
directory instead, and locks to `.radial/skills.json` beside them. Use it when
you want the pack committed with the repo so a teammate gets it by cloning, and
when the repo has wrappers: `--project` copies those alongside, so
`/team-build` is invocable directly.

```bash
radial skills install --project
```

## The team key

Every skill needs to know which Radial team to file into. It resolves in this
order, and stops at the first answer:

1. `.radial/config.json` → `{ "team": "RAD" }`
2. A `radial team` line in `CLAUDE.md` or `AGENTS.md`
3. `radial team list`, and exactly one team means use it, and write it down
4. Ask you once, then write it down

`/rd-setup` does all of this, including creating the team if you do not have
one.

## Updating and removing

```bash
radial skills update              # only what changed is rewritten
radial skills list                # installed vs published
radial skills remove rd-retro     # only the files the lock recorded
```

`update` reports one line per skill: `installed`, `updated` or `current`. It
deletes files a new version dropped, so a renamed reference file cannot linger
and get read as current. `remove` deletes only paths the lock recorded and tells
you about anything else it found in the folder rather than taking it with it.

## Other installers

The pack is a public repo with a plain `skills/` directory, so the generic
installers work with no extra hosting:

```bash
npx skills add BrainGridAI/radial
codex -- '$skill-installer --repo BrainGridAI/radial --path skills/rd-plan'
```

Both copy the same files. The CLI is the recommended door only because it ships
as a binary, verifies hashes, keeps a lock and can update and remove.

## When it does not work

| What you see | Why |
| --- | --- |
| The skill is not in the picker | The client was already running. Restart it. |
| `radial: command not found` | The CLI is not on PATH. `npm install -g radial.build`, or use the Homebrew formula. |
| Codex does not see skills that Claude Code does | Your Codex reads a different directory. `radial skills list --json` shows the directory the installer chose; compare it against `$CODEX_HOME`. |
| One skill says `failed` and the rest install | Its bytes did not match the published hash. That is the guard working: re-run, and if it persists, open an issue rather than forcing it. |
| `Refusing to fetch over plain http` | `RADIAL_SKILLS_URL` points at an `http://` origin. Use `https://`, or pass `--insecure` if it is your own mirror on a trusted network. |
| A directory is "skipped, symlink" | Your skills directory is a symlink. The installer will not write through one; point `--agent` elsewhere or replace the link. |
| Two machines disagree about what is installed | The lock is per home directory (or per repo with `--project`). Run `radial skills update` on the other one. |
| A wrapper is refused as "reserved" | `rd-*` names belong to the pack, so an update never fights your wrapper for a name. Rename it. |

<callout kind="tip">

`radial skills install --dry-run` prints exactly what it would write and touches
nothing. Useful the first time, and in a script.

</callout>