Agent Skills Setup Manager
You are helping a user manage an agent-skills monorepo — a repo that owns their coding-agent skills and exposes them via symlinks from ~/.<agent>/skills and ~/.agents/skills.
When this skill applies
Trigger phrases include: "set up agent skills", "install agent-skills-monorepo", "add codex to my setup", "repair my skills symlinks", "what agents am I managing", "show me my skills topology".
Do not invoke this skill for routine skill authoring (creating a new skill file) — only for setup / repair / topology questions about the monorepo itself.
Finding the repo
The repo root is identifiable by:
- A
setup_symlinks.py file at the root.
- An
AGENTS.md describing the monorepo.
- Top-level folders matching agent names (
agents/, claude/, optionally codex/, copilot/, cursor/, gemini/).
If you can't locate the repo, ask the user for the path. Do not guess.
Required vs optional agents
agents/ → ~/.agents/skills is canonical and always managed.
claude/ → ~/.claude/skills is a required mirror (Claude Code does not read ~/.agents/skills).
codex/, copilot/, cursor/, gemini/ are optional; the user opts in per-agent.
Standard flows
Flow A: First-time setup
- Confirm the user wants to run setup. Show the repo root you detected.
- Ask which optional agents to include (alongside the required
agents + claude). List the optional ones; default to none if the user doesn't care.
- Run the dry-run first so the user can see the plan:
python3 setup_symlinks.py --dry-run --agents=<comma,separated,list>
- Summarize what the dry run will do per agent in plain English. Highlight any backups about to be created.
- Ask for explicit confirmation, then run:
python3 setup_symlinks.py --agents=<comma,separated,list>
The script is interactive and asks for confirmation at each step; relay its prompts to the user.
- After completion, run
python3 setup_symlinks.py --status and show the result.
Flow B: Add an agent to an existing setup
- Run
python3 setup_symlinks.py --status to see what is already configured.
- Confirm which new agent the user wants to add.
- Build the new comma-separated list = previously configured + the new one.
- Run dry-run then live run as in Flow A. Already-configured agents are skipped automatically.
Flow C: Repair drift
- Run
python3 setup_symlinks.py --status and analyze the output.
- For any agent whose system path is not a symlink to the repo folder, decide with the user:
- If the system path is a foreign symlink or a non-directory, surface this and stop — do not auto-resolve.
- If the system path is a regular directory, re-running setup with that agent in the selection will import-and-link or merge it.
- Run the script with the appropriate
--agents= flag.
Flow D: Status check
Run python3 setup_symlinks.py --status and explain the output in plain language. Mention any agents that are not configured but available, and any drift.
Guardrails
- Never delete the
.agent-skills-setup/backup/ directory without explicit user permission. It is the user's safety net.
- Never force or
--no-verify anything. The script has no force mode by design.
- Never edit individual skills as part of setup work — that's out of scope for this skill.
- Always show the dry-run plan before running for real, even if the user is in a hurry.
- If the script reports an unhandled state combination, stop and ask the user. Do not improvise.
Installing new skills into the repo
When the user asks you to add or create a new skill inside this repo (separate from setup):
- Ask: "Install this skill into
agents/, claude/, or both?" Default suggestion is both.
- Remind the user that they can set a durable preference in the repo's
AGENTS.md (e.g. "always install new skills into both" or "agents-only by default") so they don't get asked every time.
- If
AGENTS.md already specifies a preference, follow it without re-asking.
- Avoid placing user skills into
codex/, copilot/, cursor/, or gemini/ unless the user explicitly says so.
Quick reference
| Task |
Command |
| Show topology |
python3 setup_symlinks.py --status |
| Preview setup |
python3 setup_symlinks.py --dry-run |
| Interactive setup |
python3 setup_symlinks.py |
| Non-interactive selection |
python3 setup_symlinks.py --agents=agents,claude,codex |
| Saved selection file |
.agent-skills-setup/config.json |
| Backups |
.agent-skills-setup/backup/<agent>/ |
| Recovery notes |
.agent-skills-setup/backup/README.md |
1---2name: agent-skills-setup-manager3description: Set up, repair, re-run, or inspect the agent-skills monorepo. Use when the user wants to install the monorepo for the first time, add a new agent (codex/copilot/cursor/gemini) to an existing setup, check the status of their symlinks, repair drift, or ask any "set up my agent skills" / "configure agent-skills-monorepo" question. Operates on the repo whose root contains `setup_symlinks.py` and `AGENTS.md` describing the agent-skills monorepo. Do NOT use for unrelated skill authoring or other repos.4metadata:5 source: https://skillmd.com/skills/zazencodes/agent-skills-setup-manager6---78# Agent Skills Setup Manager910You are helping a user manage an **agent-skills monorepo** — a repo that owns their coding-agent skills and exposes them via symlinks from `~/.<agent>/skills` and `~/.agents/skills`.1112## When this skill applies1314Trigger phrases include: "set up agent skills", "install agent-skills-monorepo", "add codex to my setup", "repair my skills symlinks", "what agents am I managing", "show me my skills topology".1516Do **not** invoke this skill for routine skill authoring (creating a new skill file) — only for setup / repair / topology questions about the monorepo itself.1718## Finding the repo1920The repo root is identifiable by:21- A `setup_symlinks.py` file at the root.22- An `AGENTS.md` describing the monorepo.23- Top-level folders matching agent names (`agents/`, `claude/`, optionally `codex/`, `copilot/`, `cursor/`, `gemini/`).2425If you can't locate the repo, ask the user for the path. Do not guess.2627## Required vs optional agents2829- `agents/` → `~/.agents/skills` is **canonical** and always managed.30- `claude/` → `~/.claude/skills` is a **required mirror** (Claude Code does not read `~/.agents/skills`).31- `codex/`, `copilot/`, `cursor/`, `gemini/` are **optional**; the user opts in per-agent.3233## Standard flows3435### Flow A: First-time setup36371. Confirm the user wants to run setup. Show the repo root you detected.382. Ask which optional agents to include (alongside the required `agents` + `claude`). List the optional ones; default to none if the user doesn't care.393. Run the dry-run first so the user can see the plan:40 ```sh41 python3 setup_symlinks.py --dry-run --agents=<comma,separated,list>42 ```434. Summarize what the dry run will do per agent in plain English. Highlight any backups about to be created.445. Ask for explicit confirmation, then run:45 ```sh46 python3 setup_symlinks.py --agents=<comma,separated,list>47 ```48 The script is interactive and asks for confirmation at each step; relay its prompts to the user.496. After completion, run `python3 setup_symlinks.py --status` and show the result.5051### Flow B: Add an agent to an existing setup52531. Run `python3 setup_symlinks.py --status` to see what is already configured.542. Confirm which new agent the user wants to add.553. Build the new comma-separated list = previously configured + the new one.564. Run dry-run then live run as in Flow A. Already-configured agents are skipped automatically.5758### Flow C: Repair drift59601. Run `python3 setup_symlinks.py --status` and analyze the output.612. For any agent whose system path is not a symlink to the repo folder, decide with the user:62 - If the system path is a foreign symlink or a non-directory, surface this and stop — do not auto-resolve.63 - If the system path is a regular directory, re-running setup with that agent in the selection will import-and-link or merge it.643. Run the script with the appropriate `--agents=` flag.6566### Flow D: Status check6768Run `python3 setup_symlinks.py --status` and explain the output in plain language. Mention any agents that are not configured but available, and any drift.6970## Guardrails7172- **Never** delete the `.agent-skills-setup/backup/` directory without explicit user permission. It is the user's safety net.73- **Never** force or `--no-verify` anything. The script has no force mode by design.74- **Never** edit individual skills as part of setup work — that's out of scope for this skill.75- Always show the dry-run plan before running for real, even if the user is in a hurry.76- If the script reports an unhandled state combination, stop and ask the user. Do not improvise.7778## Installing new skills into the repo7980When the user asks you to **add or create a new skill** inside this repo (separate from setup):8182- Ask: "Install this skill into `agents/`, `claude/`, or both?" Default suggestion is **both**.83- Remind the user that they can set a durable preference in the repo's `AGENTS.md` (e.g. "always install new skills into both" or "agents-only by default") so they don't get asked every time.84- If `AGENTS.md` already specifies a preference, follow it without re-asking.85- Avoid placing user skills into `codex/`, `copilot/`, `cursor/`, or `gemini/` unless the user explicitly says so.8687## Quick reference8889| Task | Command |90| --- | --- |91| Show topology | `python3 setup_symlinks.py --status` |92| Preview setup | `python3 setup_symlinks.py --dry-run` |93| Interactive setup | `python3 setup_symlinks.py` |94| Non-interactive selection | `python3 setup_symlinks.py --agents=agents,claude,codex` |95| Saved selection file | `.agent-skills-setup/config.json` |96| Backups | `.agent-skills-setup/backup/<agent>/` |97| Recovery notes | `.agent-skills-setup/backup/README.md` |