MercuryToolbox/skills/mercury-toolbox/SKILL.md

name, description

name	description
mercury-toolbox	Use whenever Mercury Toolbox binaries are present and the task is local terminal inspection or triage: code and log reading, structured-data shaping, repo or runtime diagnosis, process, port, or lock troubleshooting, managed assembly or Unity analysis, or when the agent would otherwise reach for Get-Content, cat, tree, grep, findstr, netstat, tasklist, or ad-hoc PowerShell glue.

Mercury Toolbox

Use this skill immediately when Mercury Toolbox binaries are present and the job is local terminal inspection, shaping, or triage. Read it first, then route through Mercury before falling back to raw dumps, legacy builtins, or ad-hoc shell glue.

First Choice Rules

• Prefer Mercury readers over Get-Content, cat, tree, tasklist, netstat, or whole-file dumps.
• For source and logs, usually start with fileprobe, outline, snip, or chunkcat, then move to hitsnip, defsnip, refs, codeshape, or ctxpack as needed.
• Prefer compact text by default, switch to --json when the next step parses the result, and switch to --toon or --format toon when the next consumer is an AI/model.
• Pipe external JSON into toon only when the producer is not a Mercury tool; TOON auto-detects JSON and emits dense TOON by default.
• Prefer stdin and pipelines over reopening the same file repeatedly.
• Pair Mercury with modern CLI companions instead of legacy builtins.
• Treat msudo as the top-level high-risk toolbox command: start with msudo status --json or --help before considering any privileged launch.

Modern Pairings

• Search and files: rg, fd, and optionally fzf or PSFzf for interactive narrowing.
• Viewing and editing: bat, hexyl, and nvim for bounded human reads instead of raw file dumps.
• Data and text: jq, yq, and sd for structured queries and small safe rewrites.
• Git and navigation: git, lazygit, delta, and zoxide when they answer the question faster than shell glue.
• Stats and diagnostics: tokei, eza, procs, dust, and hyperfine for fast shape or performance checks.
• Utilities: xh, ouch, and tealdeer for quick HTTP work, archives, and terse help.

Modern Default Replacements

• Use rg over recursive grep or broad Select-String.
• Use fd over Get-ChildItem -Recurse when you only need file discovery.
• Use bat or Mercury readers over raw Get-Content for bounded viewing.
• Use jq or yq over manual JSON or YAML parsing.
• Use sd for simple regex replacements and xh over curl for quick HTTP checks.

Fast Routing

• Code and Context: fileprobe, outline, codeshape, refs, snip, defsnip, ctxpack, chunkcat, hitsnip, diagpick, gitshape, reposhape, dotnetshape
• Data and Config: cjson, ison, isonl, zon, tonl, jsonlgrep, jsonshape, mhash, toon, csvshape, sqliteshape, sqlshape, config
• Logs, Process, and Waiting: logshape, envdiff, proctree, sysshape, runprobe, await, argv, recent, pathshadow
• Network and Locks: portping, portunlock, msudo, unlock
• Managed, Unity, and Binary Inspection: asmtype, asmmember, asmref, asmapi, asmflow, llvmobjdump, llvmreadobj, llvmnm, peexports, peimports, pecalls, pesig, pestrrefs, drvshape, ioctlscan, unityasset, unityprobe, unitydiag, binmeta, stringscan

Job Routing

• Unknown file: start with fileprobe <PATH>, then choose binmeta, stringscan, snip, or chunkcat from the detected shape.
• Repository map: start with reposhape . --json, then use codeshape, gitshape, dotnetshape, sqlshape, or ctxpack.
• Symbol or source context: start with defsnip <SYMBOL> . or refs <SYMBOL> ., then pack evidence with hitsnip or ctxpack.
• Logs and failures: start with diagpick <LOG>, then use logshape, snip --match, or runprobe.
• Managed or Unity DLL: start with asmref diagnose <ASSEMBLY> --resolve-dir <DIR>, then use asmtype, asmmember, asmflow, or asmapi diff.
• Windows EXE/DLL: start with peimports <PATH>; every catalog entry includes guided answer/trust/next actions, and PE deep tools also expose runtime report_quality and next_actions in --json/--toon.
• Windows driver: start with drvshape <SYS>, then follow ioctlscan, peimports --category device_io, pecalls --category device_io, or pestrrefs.

Read Next

• Read references/command-catalog.md beside this skill when you need command-by-command routing, usage, and examples.
• In packaged installs, the skill lives under share\\mercury-toolbox\\skills\\mercury-toolbox and the generated prompt lives under share\\mercury-toolbox\\docs\\ai.