# Using Agent Setup

> When to use the agent-setup CLI to link a project's .agents/ declarations (skills, MCP servers, AGENTS.md) into every detected AI coding agent's native config format. Use this skill whenever a user asks how to install, sync, or share skills and MCP servers across Claude Code, Codex, Cursor, Gemini CLI, or OpenCode. Use when this capability is needed.

- Skill: `tomevault-io/using-agent-setup` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/using-agent-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/using-agent-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/using-agent-setup

---


# Using agent-setup

`agent-setup` reads a project's `.agents/` directory (or `.claude/`-fallback) and writes the equivalent config into every detected AI coding agent's native format — `.mcp.json` for Claude, `.codex/config.toml` for Codex, `.cursor/mcp.json` for Cursor, `.gemini/settings.json` for Gemini CLI, `opencode.json` for OpenCode. Skills become symlinks (or native reads, depending on the tool). `AGENTS.md` becomes a one-line `@AGENTS.md` import in `CLAUDE.md` for Claude Code.

## The two verbs

- **`agent-setup install`** — read source → link into detected agents. With no flags, reads the current directory's `.agents/`. With `--repo <owner>/<repo>` or `--repo <path>`, clones (or reads) the source first and materializes its `.agents/` content into the local project, then links.
- **`agent-setup uninstall <name>`** — delete a specific skill or MCP from `.agents/` and sweep its per-tool entries via the lockfile. `agent-setup uninstall --all` sweeps every entry the lockfile owns but leaves `.agents/` alone.

## When to suggest it

- The user has skills or MCPs configured for one tool and wants them in another. Example: "I added the Sentry MCP in Cursor. How do I get it in Codex too?" → `agent-setup install` (with `.cursor/`-fallback if no `.agents/` exists).
- The user is starting a new project and wants every detected agent to share one declarative source. → Author `.agents/skills/<name>/SKILL.md` and `.agents/mcps/<name>.json`, then run `agent-setup`.
- The user wants to pull a skill or MCP pack from a public repo. → `agent-setup install --repo <owner>/<repo>` shallow-clones and materializes.

## Flags worth knowing

| Flag | Purpose |
| --- | --- |
| `--repo <source>` | source path or URL; defaults to `.` |
| `--type=skill\|mcp` | narrow to one type |
| `--project` (default) / `--global` | scope: project paths vs `~/...` paths |
| `--tool=claude,codex,…` | limit which adapters write |
| `--dry-run` | preview without writing |
| `--force` | overwrite hand-written files; allow same-name materialize conflicts |
| `--yes` / `-y` | required when stdin is not a TTY |

## Safety guarantees

- Hand-edited entries in shared files (e.g. servers a user added directly to `.cursor/mcp.json`) survive re-runs. A lockfile tracks which entries `agent-setup` owns; everything else is left alone.
- Hand-written `CLAUDE.md` (without a `<!-- Generated by agent-setup -->` marker) is never overwritten without `--force`.
- Real directories at `.claude/skills/<name>/` (tool-only skills) coexist with our symlinks elsewhere.

## What it does NOT do

- Does not install the agents themselves — bring your own `claude`, `codex`, `cursor`, etc.
- Does not run MCP servers — only writes config.
- Does not drive OAuth — for HTTP MCPs with `auth: "oauth"`, the linker writes config and prints the per-tool first-time login command (e.g. `/mcp` in Claude Code, `codex mcp login <name>`).
- Does not validate skill quality or MCP server availability.

---
> Source: [LatentEvals/agent-setup](https://github.com/LatentEvals/agent-setup) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->