/improve-my-agent-setup

name: improve-my-agent-setup
description: Audit and improve an entire agentic-development setup, including skills, context, memory, tools, models, permissions, hooks, workflow habits, and secrets hygiene. Invoke for setup reviews, workflow grading, Goblin Mode, or questions about what to improve. Supports shallow, deep, ultra, and yolo modes. Use domain-specific skills for a single model, report, or tenant.

Improve my agent setup

A setup-wide health check for someone doing agentic development. It measures what can be measured (skills, memory, config, tools, git, transcripts), interviews the user about the parts that can't be measured (ethics, focus, habits), scores each theme, writes a report to `.claude/scratchpads/`, and then offers to fix the weak spots one at a time.

The point is not a vanity score. It is to find the two or three changes that would most improve how this person works with agents, and then actually make them. A setup rots the same way a codebase does: skills pile up unused, memory bloats with things the model already knows, tools go redundant, and nobody prunes. This skill is the prune.

Guiding stance, echoed across this marketplace: every installed tool, skill, and line of memory competes for the agent's attention and context. More is not better. The best setup is the smallest one that does the job, owned and tuned by the person using it.

How to use this skill

1. Pick the audit mode from `$ARGUMENTS` (or the user's phrasing); it sets depth, interview cadence, and tone 2. Run the scan script at the breadth that mode implies, to gather deterministic facts 3. Read `references/dimensions.md` for the full rubric; it defines each theme, what good looks like, and the signals to read from the scan 4. Interpret the facts theme by theme; do not just echo the JSON 5. Interview the user for what the scan can't see; how often you interview depends on the mode 6. For the context-files theme, apply `references/context-review.md` (the absorbed context audit) 7. Write the report to `.claude/scratchpads/setup-audit-<YYYY-MM-DD>.md` using the template below 8. Walk the top fixes with the user and offer to apply them, and strongly advise a recurring re-audit; see `references/fix-catalog.md`

Do not try to fix things silently while auditing. Audit first, present the picture, then fix with consent.

Step 1: Pick the mode

The mode comes from `$ARGUMENTS` (`/improve-my-agent-setup deep`) or from how the user phrases the request. It sets four things at once: how wide the scan reaches, how many themes you dig into, how often you interview, and the tone you take. Read `references/modes.md` for the full definitions; the short version:

shallow:  quick, light glance; the basics (tools, redundancy, memory length); interview mainly up front;
          friendly. Refuse and escalate if the project turns out big or messy.
deep:     the default. Routine full checkup, user-level + cwd, without pushing the big transformational
          changes; interview at the start and on ambiguity; a doctor at a consultation.
ultra:    machine-wide and much deeper (all projects, settings, package managers, finished-vs-abandoned,
          determinism, value-for-money); interview throughout; a harsh personal trainer. High effort.
yolo:     everything findable, including mining the transcripts for error and tokenmaxxing patterns;
          relentless interview; a drill sergeant. Assumes a demolition-and-rebuild. Warn on cost. Max effort.

If no mode is given, default to `deep`. If the user's situation doesn't match the mode they asked for (a shallow run on a clearly wrecked setup), say so and offer the heavier mode rather than under-serving. Match your own reasoning effort to the mode.

Before an `ultra` or `yolo` run, do two things `modes.md` describes in full: check what model and effort are actually running (introspect your context, or glance at the recent transcript or statusline) and caution the user if it's a lighter model or effort below high, since these modes need real introspection; and for `yolo`, set a `/goal` or `/loop` first so the long run survives context limits and doesn't stop half-done.

Step 2: Run the scan

Map the mode to the scan's `--scope`: shallow and deep use `user`; ultra and yolo use `deep`. For ultra and yolo, also go machine-wide beyond cwd, enumerating the user's project dirs (the transcripts signal lists them) and sampling across them; yolo additionally reads a sample of `~/.claude/projects/*.jsonl` for patterns. Pass a project path to target one repo.

python3 "${CLAUDE_PLUGIN_ROOT}/skills/improve-my-agent-setup/scripts/scan_setup.py" --scope=<user|project|deep> [project-path] \
  > .claude/scratchpads/setup-scan.json

Pass a project path to target a specific repo; with no path it uses the current git root. The script is stdlib-only and reads metadata only. It is built so no secret material ever reaches disk: env vars and connection strings come back as keys, and the secrets sweep reports only a file path, a line number, a rule name, and a match length; never the matched value. Keep that contract; when you write the report, describe where a secret is, never what it is. If `${CLAUDE_PLUGIN_ROOT}` is not set, use the script's path under this skill directly.

The JSON has these sections: `skills`, `memory`, `settings`, `tools`, `mcp`, `git`, `transcripts`, `clients`, `secrets`. Notable ones:

• `memory.organization` flags how context is structured: whether a CLAUDE.md is just a thin pointer (for example `@AGENTS.md`), whether AGENTS.md is used, and whether a `rules/` directory organizes memory into modular files. Read it for the memory-and-context theme.
• `clients` detects the other agentic dev environments (Claude Desktop, VS Code, Cursor, Zed): whether each is set up, its MCP servers, and its rule files. Read it to catch config outside Claude Code and the same capability wired up redundantly across clients.
• `guards` reports the permis