How to prepare agent-box for (custom) skills

[lionello]

The goal is that any skill that get installed are available to all harnesses [for a user]. So if I ask claude to install a skill, it should end up somewhere where codex, opencode, etc. can also find it, and v.v..

The other part to think about is to make it super easy for the user to install 3rd party skills in a project (user). The agents is the UI.

[defangdevs]

Looked at how each harness actually discovers skills today, mapped against what agent-box already controls.

Personal/user-scope paths (this is the part agent-box owns, since $HOME is shared per-user across sessions):

• claude: ~/.claude/skills/<name>/SKILL.md
• codex: ~/.agents/skills/<name>/SKILL.md — does not read ~/.claude/skills
• opencode (not in supportedAgents yet): already reads both ~/.claude/skills and ~/.agents/skills natively — it checks 6 paths total (3 project, 3 global), including both vendor conventions

Project scope is the same shape (.claude/skills, .agents/skills, walked up to the repo root) but that lives inside the user's own project checkout — not something agent-box should be injecting into arbitrary cloned repos.

So the actual gap for goal 1 (one skill, visible to every harness) is narrow: only codex is blind to ~/.claude/skills. opencode already unifies itself across both conventions. Fix is one dangling-symlink bridge — same shape as the CLAUDE.md/AGENTS.md pointer trick already in supervisor.sh (modules/agent-box.nix ~3769-4554, from #305): pick a canonical store, symlink every harness-specific personal-skills path to it, guarded by the same [ ! -e ... ] && ln -s so a hand-created real directory is never clobbered.

I'd make the canonical store harness-neutral instead of piggybacking on ~/.claude/skills — e.g. ~/.config/agent-box/skills — then:

~/.claude/skills          -> ~/.config/agent-box/skills
~/.agents/skills          -> ~/.config/agent-box/skills
~/.config/opencode/skills -> ~/.config/agent-box/skills   # once opencode is a supported agent

Goal 2 (easy 3rd-party install) is a separate, harder problem. Claude Code already has a story here via plugins/marketplaces (claude plugin marketplace add, claude plugin install), but plugin-bundled skills live under the plugin's own directory, not under ~/.claude/skills — so the symlink bridge above won't surface those to codex/opencode. Neither codex nor opencode has an install command today either (opencode's skills doc is pure file-drop, no package manager mentioned). So a real cross-harness "install a 3rd-party skill" story reduces to "materialize files into the canonical store" — a small agent-box-skill install <source> wrapper (git clone / tarball into ~/.config/agent-box/skills/<name>/) rather than trying to unify three different plugin systems.

Happy to open a PR for the symlink bridge (small, mechanical, same pattern #305 already established) — want me to go ahead, or do you want to settle the canonical-store location first?

[defangdevs]

Worked example: I installed a 3rd-party skill on this box today

Lio asked me to install the /wait-what skill from https://www.aihero.dev/skills-wait-what. Here is what the install needed, and what it measured for both goals in this issue.

Result: installed and verified. One copy of the files, visible to claude and codex:

~/.agents/skills/wait-what/SKILL.md                      <- the only copy
~/.claude/skills/wait-what -> ../../.agents/skills/wait-what

1. The box cannot run the command the vendor page gives you

Every skills page ends with an npx line:

npx skills@latest add mattpocock/skills --skill=wait-what

npx does not exist here. The box installs nodejs-slim (node 24.18.0). That package has no npm and no npx.

I used this workaround:

nix shell nixpkgs#nodejs --command npx --yes skills@latest add ...

This is the first concrete gap. Goal 2 says "make it super easy to install 3rd party skills". Today step one is "know that nodejs-slim is not nodejs". Add nodejs to the box, or ship a wrapper that supplies npx.

2. skills.sh is already a cross-harness installer — I was wrong above

In my earlier comment I wrote that neither codex nor opencode has an install command. That is wrong. skills.sh installs to 70+ agent targets, and the list includes claude-code, codex and opencode.

It also detects that an agent runs it, and then it asks no questions:

●  claude-code_2-1-238_agent  Agent detected — installing non-interactively

That is exactly the "the agents is the UI" shape. I drove the whole install from a tool call, with no TTY.

3. Two flag traps, both of which cost me a re-install

• --skill=wait-what is silently ignored. The equals form is the one printed on the vendor page. It installed all 37 skills in the repo into ~/.claude/skills. The space form -s wait-what installs 1. I had to remove 38 skills and start again.
• A comma list of agents is refused: -a claude-code,codex gives Invalid agents. Repeat the flag instead: -a claude-code -a codex.

The command that does what the page promises is:

npx skills@latest add mattpocock/skills -s wait-what -g -a claude-code -a codex -y

4. The installer already does the canonical-store trick itself

With more than one agent target, it writes one copy and symlinks the others to it:

✓ ~/.agents/skills/wait-what
  universal: Codex
  symlinked: Claude Code

With -a claude-code alone it writes a real copy into ~/.claude/skills/wait-what, and codex never sees it. That default is the failure mode this issue must fix: a user who copies the plain command off a vendor page gets a claude-only skill.

5. MEASURED: a pre-made bridge symlink survives the installer

I built a sandbox $HOME with the bridge from my earlier comment:

~/.claude/skills -> ~/.config/agent-box/skills
~/.agents/skills -> ~/.config/agent-box/skills

Then I ran the installer into it. After the install:

• both symlinks were intact — the installer did not clobber either one;
• the only copy of the files was ~/.config/agent-box/skills/wait-what/;
• the installer's own "symlink Claude Code to the store" step became a no-op, because the target was already the store.

So the bridge is compatible with skills.sh, and it repairs the §4 default: with the bridge in place, even a claude-only install lands in the shared store.

6. codex path facts (measured, 0.147.0)

I tested with a plain probe skill, because wait-what is invisible for a different reason (see §7):

probe location	codex lists it
~/.codex/skills/zz-probe/	yes
~/.agents/skills/zz-probe/	yes
removed from both	no (negative control)

So codex reads both ~/.agents/skills and ~/.codex/skills. My earlier claim about ~/.agents/skills holds, and ~/.codex/skills is a second root I missed.

Two consequences for the bridge:

• ~/.codex/skills cannot be a directory symlink. It is a real directory already, and it holds codex's 6 preinstalled skills in ~/.codex/skills/.system/ (imagegen, openai-docs, plugin-creator, review-agent, skill-creator, skill-installer). A directory-level symlink would hide them.
• That does not matter, because ~/.agents/skills is enough for codex. ~/.agents/skills is the right canonical store, not ~/.config/agent-box/skills as I proposed above: codex reads it natively, opencode reads it natively, and skills.sh already picks it by itself for multi-agent installs. Then only ~/.claude/skills needs the bridge symlink, and the design shrinks to one line.

Codex also ships a bundled skill-installer skill that installs from GitHub into $CODEX_HOME/skills/<name>. It is a second, codex-only install path that writes to a store the bridge does not own. Worth knowing before we call goal 2 solved.

7. Do not use "the agent lists it" as your install test

wait-what sets disable-model-invocation: true (and allow_implicit_invocation: false in its agents/openai.yaml). That hides it from the model's list of available skills on purpose — only the user may start it. My first codex test read that as "not installed" and sent me looking for a path bug that did not exist. Any check we build has to test the file, not the agent's self-report.

8. Security note

The installer prints a risk assessment (Gen / Socket / Snyk) and closes with Review skills before use; they run with full agent permissions. It also has an install-telemetry event (--metadata <json>). If the box ever wraps this command, keep that warning visible.

Where this leaves the plan

I still think the symlink bridge is right, and it is now smaller than what I proposed:

~/.claude/skills -> ~/.agents/skills     # guarded: only if nothing is there

That single link makes the vendor-page default (§4) cross-harness, and §5 shows the installer writes through it instead of breaking it. Say the word and I will open that PR.

For goal 2, my agent-box-skill install sketch above is now the wrong shape — skills.sh already does the job for all three harnesses. The cheaper move is to make npx work (§1) and document the correct flags (§3).