agent-setup
One command that sets up three different coding agents with the same
skills, instructions and tools for working on the simonjamesrowe org:
- Claude Code (Anthropic) —
~/.claude/ - Gemini CLI (Google) —
~/.gemini/ - Codex (OpenAI) —
~/.codex/
Skills are authored once, in agent-agnostic markdown, and fanned out to each
tool's native location — so switching agents doesn't mean starting from a
blank slate. agent-setup also registers MCP servers and installs CLI
plugins for whichever of the three it finds on your PATH.
What each agent gets
Quick start
npx @simonjamesrowe/agent-setup
Check what's installed without changing anything:
npx @simonjamesrowe/agent-setup doctor
Flags
Commands: install (default), doctor (check-only), help.
Without --tools, agent-setup auto-detects which of claude, gemini and
codex are on PATH and only provisions those.
What gets installed
Destinations
- Skills (
components/skills/) are copied verbatim into each detected tool's skills directory. - Instructions (
components/instructions/global.md) are merged into each tool's instructions file inside a marked block (``), so re-running install updates the block in place without disturbing anything you've added outside it.doctorreports the block asmissingif it's absent or has been edited/clobbered.
Skills
See docs/SKILLS.md
for naming conventions, where a new skill should live, the SKILL.md format
contract, and the checklist for adding one.
MCP servers
Registered at user scope for every detected agent.
playwright, excalidraw, javadocs, linear, simonrowe-dev and
embabel-guide, honeycomb and amplitude are agent-setup's own catalog (MCP_SERVERS in
lib/provisioners/mcp.js). moderne is not in that array — it's
registered by the mod CLI itself (mod config agent-tools <agent> install,
see CLI tools below), not by agent-setup's MCP provisioner.
simonrowe-dev is the site's own MCP server, served by the Spring Boot backend
at https://api.simonrowe.dev/mcp (streamable HTTP, no auth, no local
process — it is up whenever the API is). It gives every agent first-hand access
to the live site content instead of guessing: getProfile, getJobs,
getSkills, searchBlogs, getRecentBlogs, searchNews,
getUpcomingEvents, getCodeExamples, searchSite and submitContactForm.
The last of those emails Simon and is the only side-effecting tool; the server
rate-limits it to once per session itself.
A server already registered at project or local scope would shadow the
user-scope one, so that's reported as failed with the mcp remove command
to fix it rather than being silently overwritten.
linear, honeycomb and amplitude use interactive OAuth, so
registration and authorization are separate steps: install registers it, then
you sign in once yourself, with your agent's own command:
(Verified 2026-08-25: codex mcp login --help on codex-cli 0.133.0, and
gemini-cli 0.49.0's own docs/tools/mcp-server.md, which documents
/mcp auth serverName. Gemini has no gemini mcp login subcommand.)
Until you do, doctor reports the row as optional — registered but not authorized — rather than unchanged, because the server is configured but its
tools do not work. That row never affects the exit code, since the sign-in is a
browser flow agent-setup cannot perform for you. Auth state is only
detected for Claude Code: claude mcp get prints a Status: line that says
so, Gemini's check reads ~/.gemini/settings.json (which carries no auth
metadata at all), and Codex's unauthorized output is still unverified.
Honeycomb and Amplitude
Install either or both with agent-setup install --with honeycomb,amplitude.
The same authorization commands above apply, replacing linear with the server name.
Signing into the website with Google does not itself authorize an MCP client.
The catalog defaults to US. For an EU account, remove and re-add the server using its regional URL before signing in:
For example: codex mcp remove honeycomb, then
codex mcp add honeycomb --url https://mcp.eu1.honeycomb.io/mcp.
Existing registrations are matched by name, so subsequent installs preserve this override.
Claude Code uses mcp remove <name> -s user and
mcp add --scope user --transport http <name> <url>.
Honeycomb MCP is included in Free; enable Team Intelligence and authorize only
mcp:read for investigation (codex mcp login honeycomb --scopes mcp:read).
Its ingest key is a separate server-side credential and cannot authorize MCP queries.
For Amplitude, request read-only access with
codex mcp login amplitude --scopes all:read,offline_access (verified against
the hosted US OAuth server). Amplitude OAuth also inherits the user's project permissions; use a role with MCP read
access and no write access if appropriate. Service-account authentication requires
Enterprise, so it is not part of this Free-tier setup. Neither integration ships tokens.
Verify a read-only tool call after login; registration alone is not proof of access.
Sources: Honeycomb MCP and Amplitude MCP.
Read-only Linear
If you would rather agents never write to your tracker, remove the server and re-add it against Linear's read-only endpoint — same server, search and read only:
claude mcp remove linear -s user
claude mcp add --scope user --transport http linear https://mcp.linear.app/mcp/readonly
--scope user is not optional: claude mcp add defaults to local scope
(claude mcp add --help, Claude Code 2.1.220, 2026-08-25), and a local-scope
linear shadows the user-scope one — which agent-setup reports as failed.
Use the equivalent remove/add pair for Codex or Gemini.
The swap survives future upgrades because agent-setup's registration check
matches on the server name only, never on the URL: execBasedCheck in
lib/provisioners/mcp.js looks for the name in mcp get output, and the Gemini
check looks for the mcpServers key. So a readonly-swapped linear reports
unchanged on every later install run and is never clobbered. Editing the URL
inside the installed npm package would not survive the next global install;
this does.
CLI tools and plugins
mattpocock-skills — the process layer
mattpocock/skills (MIT) replaced
superpowers in 1.0.0. It carries 25 skills: grill-me/grilling (a
design-tree interview that stress-tests a plan before any code is written),
tdd, code-review, diagnosing-bugs, domain-modeling, to-spec,
to-tickets, research, handoff and more.
Installed from upstream rather than vendored into components/skills/, so it
tracks the source instead of drifting from a frozen copy.
Reaching all three agents takes two different mechanisms, because only two of them have a plugin system:
Codex reads Claude-format marketplaces. Verified 2026-09-06 on codex-cli
0.150.1: codex plugin marketplace add mattpocock/skills resolves the repo's
.claude-plugin/marketplace.json and registers the marketplace as mattpocock
(the marketplace name comes from that file, not from the repo name — the two
differ here). The install verb is plugin add, not plugin install, and Codex
has no plugin enable.
Gemini has no plugin mechanism at all, but gemini skills install <git-url> --path <subdir> clones a repo once and installs every SKILL.md beneath one
subdirectory. The two paths are skills/engineering and skills/productivity
rather than skills — the repo also carries skills/in-progress (8) and
skills/misc (4), which the upstream plugin manifest deliberately excludes.
These land in ~/.gemini/skills/ alongside this repo's own 20 skills; there is
no name collision today, and neither set clobbers the other.
grill-me is invisible to the model, by design. It ships
disable-model-invocation: true, so Claude and Codex both hide it from the
model's skill list and only surface it when you type it. The model-visible
half is grilling, which carries the actual interview loop. grill-me is a
one-line entry point that calls it.
superpowers is removed, not just unmanaged
superpowers was installed by this tool for Claude Code up to 0.4.1, and
OpenAI's own openai-curated marketplace offers it to Codex as well. From 1.0.0
install actively uninstalls it from both: an orphaned superpowers keeps
injecting its SessionStart block into every session, which is the standing
context cost this change exists to remove.
doctor reports a still-installed superpowers as missing — the one place
that status means "present, and should not be" — so a machine that has not run
the migration exits non-zero. This is a one-release migration and will be
dropped once every machine has run 1.x.
mod config agent-tools <agent> install registers the Moderne MCP server
and installs Moderne's own OpenRewrite skills for that agent, so
agent-setup calls it once per supported agent (claude, codex) rather
than reimplementing either step. It deliberately never runs the blanket
mod config agent-tools install — that form provisions all eight agents
Moderne supports regardless of which ones agent-setup was asked to
provision, and it writes .github/instructions/ and .vscode/mcp.json into
whatever directory it happens to be run from. Gemini CLI is not a supported
target for mod config agent-tools upstream and is reported as skipped.
Recipes resolve from Maven Central today, so mod needs no credential to run
the current Spring Boot upgrade recipe. A Code Genome Project token only
matters once you need a recipe release newer than Central carries — the
one-time setup for that is in the spring-boot-upgrade skill.
Optional components
Not installed by default; opt in by name.
npx @simonjamesrowe/agent-setup --with embabel-guide
doctor reports opted-out components as optional, never missing, so they
don't affect its exit code.
Platform support: macOS and Linux. Windows is untested — tool detection shells out to
which.
Updating
Re-run the same command to pick up new skills, instructions or plugin versions — install is idempotent and only touches what's changed:
npx @simonjamesrowe/agent-setup
Version policy
- patch — wording or fix (skill body edit, instructions tweak, bug fix)
- minor — new skill or new flag (backward-compatible addition)
- major — rename or removal (a skill, flag or destination changes shape or disappears)
Development
git clone [email protected]:simonjamesrowe/agent-setup.git
cd agent-setup
npm test
npm run lint:skills
Smoke-test an install into a disposable target directory instead of your real home directory:
node bin/agent-setup.js install --yes --target "$(mktemp -d)" --tools claude,gemini,codex --skip mcp,plugins
License
MIT — see LICENSE.
