Improve My Agent Setup

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 permission default_mode, whether a supply-chain install guard is present (release_age_guard), and whether the secret-read verb is blocked (secret_read_block). Read it for the permission-posture and supply-chain themes.
• environment reports the isolation rung (isolation_degree: container / vm / bare-metal / unknown), the os_user, and container/VM indicators. Read it with guards.default_mode: a permissive mode is a very different risk on the bare host as your everyday user than in a throwaway box or under a separate user.
• safety_instructions counts declared "never X" safety rules in memory (by_category, samples). These are non-binding suggestions; cross-reference them against guards and hooks to judge which are actually enforced (the safety-enforcement theme).
• network reports mesh-VPN CLIs and, at deep scope only, non-loopback listening ports (exposed_listeners, wildcard_bind_count); autonomous_agents reports detected agent runtimes. Both feed the network-and-autonomous-exposure theme and are meaningful mainly at ultra/yolo, where the enumeration actually runs.
• input_methods reports installed speech-to-text (has_stt, stt_apps, stt_clis) for the input-ergonomics theme; whether they actually use it is an interview point.
• alternatives reports local / OSS harnesses and model runners found (explores_local_or_oss, local_harness_clis, local_model_apps) for the model-independence theme.
• secrets lists candidate secret and PII hits (secret_hits) and any .env files with their git exposure. These are candidates, not confirmed leaks; triage them (see the secrets theme).

Two things the scan cannot see on its own, so check them yourself:

• MCP servers from plugins. The scan reads config files only; servers a plugin ships (for example microsoft-learn, figma, claude-in-chrome) will not appear there. Cross-check the MCP tools actually available in your session before concluding someone has "no MCP".
• Live model and effort. Read the model powering the current session and any effort setting from your own context, not just the model field in settings.

Step 3: Interpret, theme by theme

references/dimensions.md is the rubric. Work each theme, read the relevant scan signal, and form a judgment with a short reason. The themes:

skills-and-ownership:   count, overlap, redundancy, tuned-vs-as-is, vendor vs owned, shared/symlinked
memory-and-context:     token budget, redundancy across scopes, obvious-facts, organization, quality
tools-and-redundancy:   right tools present, and the WRONG kind of overlap (cli + connect-pbid both)
input-ergonomics:       speech-to-text (Wispr Flow, /voice) for longer, richer prompts
model-independence:     exploring local / OSS models + harnesses as a cost and access hedge
cross-client:           Claude Desktop / VS Code / Cursor / Zed setup and MCP redundancy across them
harness-config:         statusline content, hooks as guardrails, permission allowlist, output style
version-control:        git present, github/ado remote, commit cadence, are they logging their work
permission-posture:     default mode (auto expected); bypass only when sandboxed
execution-environment:  isolation ladder (box>vm>container>user>none) + trust-domain separation
network-and-autonomous-exposure:  private mesh vs exposed ports; uncontainerized autonomous agents (deep-level)
safety-enforcement:     declared "never X" rules vs what actually enforces them
supply-chain-defense:   blocking installs of packages published in the last ~48h
secrets-hygiene:        secrets / PII / passwords in plaintext, .env exposure in git
delegation-and-ethics:  what they delegate to agents, and whether any of it is unethical to delegate
determinism:            nondeterministic where a script would be right, and vice versa
focus-and-shipping:     many half-built projects vs sustained focus that ships
model-and-effort:       expensive model / max effort on trivial work, or the reverse
usage-review:           do they ever look at their own transcripts, cost, or usage
automation:             /loop, /schedule, goals, multiplexers, cloud agents for async delegation
knowledge-system:       is there any way memory and context compound over time, tailored to them

Judgment beats measurement. A person with 40 skills that all earn their place is fine; a person with 8 that all overlap is not. Read the reason, not the count. When the scan and your read disagree, trust your read and say why.

Step 4: Interview for what the scan can't see

Some themes have no reliable file signal. Ask, don't guess. Use AskUserQuestion, batch related questions, and let the mode set the cadence: shallow asks mainly up front; deep asks at the start and on ambiguity; ultra and yolo interview throughout, following each answer with the next probe like a doctor working a differential. Good starting questions:

• Delegation: "What do you hand to agents unsupervised?" then probe for the anti-patterns in references/dimensions.md (docs they never read, posts in their name, review-rubber-stamping)
• Shipping: "Of the projects you started this quarter, how many shipped or reached someone else?" The transcript scan shows how many project dirs exist; contrast that with what actually shipped
• Usage review: "When did you last read one of your own transcripts or check your spend?"
• Automation: "Do you use /loop, /schedule, goals, a multiplexer, or cloud agents, and for what?"

Ask only what you cannot infer. If the scan already answers it, skip the question and say what you found.