| name | using-agent-setup |
| description | 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. |
| homepage | https://github.com/latentevals/agent-setup |
| repository | https://github.com/latentevals/agent-setup |
| license | MIT |
| tags | ["skills","mcp","agents","tooling"] |
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.
