docs: rename and refresh mat-cli skill (#9)

Signed-off-by: Kai Wang <kwang@apache.org>

Author: Demogorgon314

README.md

@@ -34,10 +34,10 @@ brew install Demogorgon314/mat-cli/mat-cli
 
 ### Skills
 
-If you use the skills CLI from [`vercel-labs/skills`](https://github.com/vercel-labs/skills), install the MAT heap-dump investigation skill with:
+If you use the skills CLI from [`vercel-labs/skills`](https://github.com/vercel-labs/skills), install the MAT CLI skill with:
 
 ```bash
-npx skills add https://github.com/Demogorgon314/mat-cli --skill mat-cli-heapdump-investigator
+npx skills add https://github.com/Demogorgon314/mat-cli --skill mat-cli
 ```
 
 ### Release Zip

skills/mat-cli-heapdump-investigator/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: mat-cli
+description: Investigate Java heap dumps with Eclipse MAT CLI. Use when Codex needs to triage `.hprof` or `.phd` dumps, find dominant retainers or exploding classes, inspect object fields or nested values, trace paths to GC roots, review heap-derived thread state, run MAT reports, or escalate to OQL for targeted heap forensics.
+---
+
+# Heap Dump Analysis with mat-cli
+
+Use `mat-cli` as the first-line tool for Java heap-dump triage. Prefer the dedicated CLI commands with stable JSON contracts, then escalate to `query` or `oql` only when a direct command cannot answer the question cleanly.
+
+If `mat-cli` is unavailable, install it with `brew install demogorgon314/mat-cli/mat-cli`. Inside the MAT source tree, you can also build it from `parent/` with `mvn clean package -DskipTests -Dmat-product=mat-cli`.
+
+## Quick start
+
+- Confirm `mat-cli` is reachable with `mat-cli --help`.
+- Prefer `--format json` while reasoning, then rerun one or two focused commands with `--format text` when you need readable excerpts for the user.
+- Use absolute heap paths and keep every suspect object's `0x...` address in your notes.
+- Keep companion files beside the heap when possible. For OpenJ9 `.phd` dumps, a nearby `javacore` can improve thread analysis.
+- Use `--query-file` or `--command-file` for long expressions, embedded quotes, regexes, baseline paths, or inner class names containing `$`.
+
+```bash
+mat-cli summary <heap> --format json
+mat-cli biggest-objects <heap> --format json --limit 20 --depth 3
+mat-cli objects <heap> --by class --format json --limit 30
+mat-cli instances <heap> --class com.example.CacheEntry --format json --limit 20
+mat-cli inspect-object <heap> --object 0x1234abcd --field-paths value --format json
+mat-cli path2gc <heap> --object 0x1234abcd --format json --depth 8 --limit 20
+```
+
+If the leak might be thread-local, blocked, or finalizer-related, insert `mat-cli threads <heap> --format json --limit 20` right after `summary`.
+
+## Command map
+
+### Baseline
+
+```bash
+mat-cli summary <heap> --format json
+mat-cli threads <heap> --format json --limit 20
+```
+
+Use `summary` for heap format, object count, class count, and used heap. Use `threads` early when the leak might be thread-local, blocked, or finalizer-related. Thread output is best-effort heap metadata, not a live `jstack`.
+
+### Dominators
+
+```bash
+mat-cli biggest-objects <heap> --format json --limit 20 --depth 3
+mat-cli objects <heap> --by class --format json --limit 30
+mat-cli objects <heap> --by package --format json --limit 20
+mat-cli objects <heap> --by class-loader --format json --limit 20
+```
+
+Use `biggest-objects` to find the top retained dominators. Use `objects --by class` for class growth, `objects --by package` for retained package trees, and `objects --by class-loader` for class-loader ownership. Keep `_address` values from `biggest-objects` rows for follow-up inspection.
+
+### Class drilldown
+
+```bash
+mat-cli instances <heap> --class com.example.CacheEntry --format json --limit 20
+mat-cli instances <heap> --class-regex 'com\\.example\\..*Cache.*' --format json --limit 20
+mat-cli instances <heap> --class-contains ThreadLocal --include-subclasses --format json --limit 30
+```
+
+Use `instances` when the user names a class or when `objects --by class` points at one. Prefer `--class` for exact matches. Use regex or contains matching only when the package or suffix is uncertain. Add `--include-subclasses` only when inheritance matters.
+
+### Object inspection
+
+```bash
+mat-cli inspect-object <heap> --object 0x1234abcd --format json --depth 4 --limit 20
+mat-cli inspect-object <heap> --object 0x1234abcd --select-fields value --format json --limit 20
+mat-cli inspect-object <heap> --object 0x1234abcd --field-paths cleaner.offsetMap --format json
+mat-cli inspect-object <heap> --object 0x1234abcd --format text --field-paths count
+```
+
+Use `inspect-object` when you need concrete field values from one object. Reach for `--select-fields` when direct fields are the payload, `--field-paths` for one or more nested values, and `--show-nulls` only when null references are part of the bug story. Increase `--depth` carefully; the default is intentionally conservative.
+
+### Retention
+
+```bash
+mat-cli path2gc <heap> --object 0x1234abcd --format json --depth 8 --limit 20
+mat-cli query <heap> --command "show_dominator_tree 0x1234abcd" --format json --limit 20 --depth 4
+mat-cli query <heap> --command "merge_shortest_paths -groupby FROM_GC_ROOTS com.example.CacheEntry" --format json --limit 20 --depth 4
+```
+
+Use `path2gc` for the shortest retaining path to GC roots. Use `show_dominator_tree` when `path2gc` is too narrow and you need local dominator context. Use `merge_shortest_paths` when many leaking instances appear to flow through one shared retaining structure. If `path2gc` says the object is already a GC root, say that explicitly and pivot back to `inspect-object`, `threads`, or a dominator query.
+
+### Advanced MAT queries
+
+```bash
+mat-cli query <heap> --command "thread_overview" --format json
+mat-cli query <heap> --command "finalizer_thread" --format json
+mat-cli query <heap> --command "default_report org.eclipse.mat.api:suspects" --format json
+mat-cli query <heap> --command "default_report org.eclipse.mat.api:overview2 -params baseline=/abs/path/baseline.hprof" --format json
+mat-cli oql <heap> --query-file suspects.oql --format json --limit 20
+```
+
+Use `query` for registered MAT reports and analyses that do not have dedicated CLI wrappers. Use `oql` only after `objects`, `biggest-objects`, `instances`, `inspect-object`, or `path2gc` stop being expressive enough. Prefer `--command-file` or `--query-file` when quoting gets awkward.
+
+## Command discovery
+
+```bash
+mat-cli describe summary --format json
+mat-cli describe objects --format json
+mat-cli schema inspect-object --format json
+mat-cli list-queries --format json
+mat-cli describe-query histogram --format json
+```
+
+Use `describe` and `schema` before scripting against a CLI command's JSON output. Use `list-queries` and `describe-query` before reaching for less familiar MAT query ids or arguments. `histogram` is still useful as a MAT query id, but it is no longer the preferred first-line CLI command for class aggregation.
+
+## Reporting rules
+
+- Separate shallow heap from retained heap.
+- Quote exact class names and object addresses.
+- Treat `objects --by class` and `objects --by class-loader` retained sizes as approximate unless the command guarantees otherwise.
+- Tie each leak suspect to at least two pieces of evidence, such as a `biggest-objects` row, an `objects` view, a `path2gc` chain, a field value, a thread entry, or a MAT report section.
+- Call out uncertainty clearly when stack frames are missing or when the dump only offers best-effort thread metadata.
+- Prefer a short evidence chain over dumping raw JSON or huge tables back to the user.
+
+## Specific tasks
+
+- Ready-to-run command sequences and advanced MAT query patterns: [references/command-playbook.md](references/command-playbook.md)
+- Validated OQL snippets when direct commands are not enough: [references/oql-recipes.md](references/oql-recipes.md)

skills/mat-cli-heapdump-investigator/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "MAT CLI"
+  short_description: "Triage Java heap dumps with MAT CLI"
+  default_prompt: "Use $mat-cli to triage this heap dump with mat-cli, isolate leak suspects, inspect retaining paths, and summarize the evidence."

skills/mat-cli/SKILL.md

@@ -25,29 +25,33 @@ Use these first:
 
 ```bash
 mat-cli summary <heap> --format json
-mat-cli describe top-consumers --format json
+mat-cli describe objects --format json
 mat-cli schema threads --format json
 ```
 
-Use `describe` or `schema` when you need to know the stable JSON payload before scripting against a command. The dedicated commands already return stable `mat-cli/v2` envelopes, so prefer them over free-form MAT queries whenever possible.
+Use `describe` or `schema` when you need to know the stable JSON payload before scripting against a command. The dedicated commands already return stable `mat-cli/v1` envelopes, so prefer them over free-form MAT queries whenever possible.
 
 ## Biggest Objects and Dominators
 
 Start with retained heap, not just object count:
 
 ```bash
-mat-cli top-consumers <heap> --format json --limit 20 --depth 3
-mat-cli histogram <heap> --format json --limit 30
+mat-cli biggest-objects <heap> --format json --limit 20 --depth 3
+mat-cli objects <heap> --by class --format json --limit 30
+mat-cli objects <heap> --by package --format json --limit 20
+mat-cli objects <heap> --by class-loader --format json --limit 20
 ```
 
 Interpret the output like this:
 
-- `top-consumers` answers "what dominates retained memory right now?"
-- `histogram` answers "which classes are numerous or large in aggregate?"
-- `top-consumers.biggestObjects[].objectAddress` is the best bridge into `inspect-object`, `path2gc`, and `show_dominator_tree`.
-- `histogram` is a table result. Look for `class_name`, instance count, shallow heap, and retained heap columns.
+- `biggest-objects` answers "what dominates retained memory right now?"
+- `objects --by class` answers "which classes are numerous or large in aggregate?"
+- `objects --by package` answers "which package tree dominates retained memory?"
+- `objects --by class-loader` answers "which loaders own the most retained memory and classes?"
+- `biggest-objects.items[]._address` is the best bridge into `inspect-object`, `path2gc`, and `show_dominator_tree`.
+- `objects --by class` is a table result. Look for `class`, instance count, shallow size, and retained size columns.
 
-Use a smaller `--limit` when you only need the top suspects. Keep `histogram` tight enough to stay readable, then rerun with a larger limit only if the tail still looks interesting. Increase `--depth` on `top-consumers` when package aggregation matters.
+Use a smaller `--limit` when you only need the top suspects. Keep `objects --by class` tight enough to stay readable, then rerun with a larger limit only if the tail still looks interesting. Increase `--depth` on `biggest-objects` when you need deeper dominator levels.
 
 ## Class-Focused Drilldown
 

skills/mat-cli/agents/openai.yaml

@@ -1,6 +1,6 @@
 # MAT CLI Heapdump OQL Recipes
 
-Use these only after the dedicated commands fail to answer the question cleanly. For one object and one field, `inspect-object` is usually simpler and safer than OQL.
+Use these only after `objects`, `biggest-objects`, `instances`, and `inspect-object` fail to answer the question cleanly. For one object and one field, `inspect-object` is usually simpler and safer than OQL.
 
 ## Useful Pseudo Fields
 
@@ -11,7 +11,7 @@ MAT OQL exposes metadata fields that are useful in leak analysis:
 - `@retainedHeapSize`
 - `@name`
 
-Use them to connect OQL results back to `inspect-object`, `path2gc`, or `top-consumers`.
+Use them to connect OQL results back to `inspect-object`, `path2gc`, or `biggest-objects`.
 
 ## List Objects with Address and Readable Value