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  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.

Using agent-setup

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  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.

using-agent-setup