Repository navigation
feat: add pt-snap-helper skill and agent help epilog #144
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,169 @@ | ||
| --- | ||
| name: pt-snap-helper | ||
| description: Use as the first pt-snap entry when the next skill is unclear. Routes by user goal and input type (existing SnapshotDB, pickle-only, missing CLI, Ascend NPU collection) to pt-snap-setup, pt-snap-ascend-npu-collect, pt-snap-memory-leak, pt-snap-memory-peak-breakdown, or pt-snap-memory-fragmentation. Prefers --json on commands that currently support it. | ||
| --- | ||
|
|
||
| # pt-snap-helper | ||
|
|
||
| ## Overview | ||
|
|
||
| This is a read-only navigator. Choose the next skill from the user's goal and | ||
| input type. Do not install packages, do not copy skills into agent directories, | ||
| do not import or deserialize pickle, and do not persist focus. | ||
|
|
||
| Use this skill when: | ||
|
|
||
| - The user first asks about pt-snap and the next skill is unclear. | ||
| - The host has several pt-snap skills and needs a routing decision. | ||
| - The user has a SnapshotDB, a pickle, no CLI, or needs Ascend NPU collection. | ||
|
|
||
| Do not use this skill to run leak, peak, or fragmentation analysis. Hand off to | ||
| the matching diagnostic skill after routing. | ||
|
|
||
| ## Prerequisite: check skill availability | ||
|
|
||
| If `pt-snap` is on PATH, inspect bundled skill status with JSON: | ||
|
|
||
| ```bash | ||
| command -v pt-snap | ||
| pt-snap skill list --json | ||
| ``` | ||
|
|
||
| Parse `skills[].name` and `skills[].status`. Status is `installed`, `outdated`, | ||
| or `missing`. | ||
|
|
||
| If `pt-snap` is missing, stop routing diagnostics and hand off to | ||
| `pt-snap-setup`. Do not install the Python package from this skill. | ||
|
|
||
| If a needed skill is `missing` or `outdated`, tell the user how to install or | ||
| upgrade it. Do not run install or upgrade from this skill. | ||
|
|
||
| Install or upgrade examples the user can run after they confirm they want | ||
| the skills installed or updated. Do not run these commands from this skill: | ||
|
|
||
| ```bash | ||
| pt-snap skill install pt-snap-helper --json | ||
| pt-snap skill install --json | ||
| pt-snap skill upgrade pt-snap-helper --json | ||
| pt-snap skill upgrade --json | ||
| ``` | ||
|
|
||
| After any install, upgrade, or uninstall that changes skill files, the host | ||
| agent must be restarted before the change is visible: | ||
|
|
||
| Restart the agent after install, upgrade, or uninstall so the skill change takes effect. | ||
|
|
||
| `pt-snap skill list` does not require a restart. | ||
|
|
||
| ## Prefer `--json` where supported | ||
|
|
||
| Prefer `--json` on commands that currently accept it: | ||
|
|
||
| - `pt-snap skill list --json` | ||
| - `pt-snap skill install --json` | ||
| - `pt-snap skill upgrade --json` | ||
| - `pt-snap skill uninstall --json` | ||
| - `pt-snap metadata '<db_path>' --json` | ||
| - `pt-snap report peak-memory '<db_path>' --device <device_id> --json` | ||
|
|
||
| Do not add `--json` to `query`, `focus`, `import`, `split`, or `config`. Those | ||
| commands do not support it yet. Do not invent a global `--json` flag on `pt-snap`. | ||
|
|
||
| This skill itself does not run analysis queries. The diagnostic skills own | ||
| those commands. | ||
|
|
||
| ## Routing matrix | ||
|
|
||
| Choose one next skill. If the goal is still ambiguous after this table, ask | ||
| the user; do not start all diagnostic skills. | ||
|
|
||
| | User goal | Existing SnapshotDB | Only pickle | `pt-snap` missing | Need Ascend NPU capture | | ||
| | --- | --- | --- | --- | --- | | ||
| | Install or verify the CLI | `pt-snap-setup` | `pt-snap-setup` | `pt-snap-setup` | `pt-snap-setup` | | ||
| | Collect an Ascend NPU pickle | `pt-snap-ascend-npu-collect` | `pt-snap-ascend-npu-collect` | `pt-snap-setup` first | `pt-snap-ascend-npu-collect` | | ||
| | Leak / live allocations at end of trace | `pt-snap-memory-leak` | Trusted import first, then leak | `pt-snap-setup` first | Collect first, then trusted import, then leak | | ||
| | What was live at a peak event | `pt-snap-memory-peak-breakdown` | Trusted import first, then peak | `pt-snap-setup` first | Collect first, then trusted import, then peak | | ||
| | Allocator gaps / reserved-pool pressure | `pt-snap-memory-fragmentation` | Trusted import first, then fragmentation | `pt-snap-setup` first | Collect first, then trusted import, then fragmentation | | ||
|
|
||
| Exact next-skill names: | ||
|
|
||
| - `pt-snap-setup` | ||
| - `pt-snap-ascend-npu-collect` | ||
| - `pt-snap-memory-leak` | ||
| - `pt-snap-memory-peak-breakdown` | ||
| - `pt-snap-memory-fragmentation` | ||
|
|
||
| CSV, SVG, and other visualization files are not SnapshotDB input. If the user | ||
| only has those, stop and ask for a `.db` or a trusted pickle. | ||
|
|
||
| ### Existing SnapshotDB | ||
|
|
||
| A SnapshotDB is a pt-snap SQLite database (typically `.db`) with a | ||
| `dictionary` table. When the user already has one: | ||
|
|
||
| 1. Confirm the goal is leak, peak, or fragmentation. | ||
| 2. Hand off to the matching diagnostic skill. Pass the database path and | ||
| device if the user supplied them. | ||
| 3. Do not run `pt-snap focus <database_path>` to persist a new focus from this | ||
| skill. Diagnostic skills may read the current focus with no arguments. | ||
|
|
||
| This helper may mention that `pt-snap metadata '<db_path>' --json` exists. | ||
| Running that check belongs to the diagnostic skill. | ||
|
|
||
| ### Only pickle | ||
|
|
||
| A `.pkl` / `.pickle` file is not a SnapshotDB. Pickle import is trusted-code | ||
| execution, not a sandbox. | ||
|
|
||
| From this skill: | ||
|
|
||
| - Do not open, import, inspect, or deserialize pickle input. | ||
| - Do not run `pt-snap import`. | ||
| - Do not run `pt-snap split`. | ||
| - Do not run `pt-snap focus` with a database path. | ||
|
|
||
| Tell the user that import is an independent trusted-input decision. If they | ||
| confirm the pickle is trusted and they want a SnapshotDB, they can run: | ||
|
|
||
| ```bash | ||
| pt-snap import <snapshot.pkl> | ||
| ``` | ||
|
|
||
| That command currently has no `--json` option. Import may update focus unless | ||
| they pass `--no-focus`. This helper must not run that command or change focus. | ||
|
|
||
| After the user has a SnapshotDB, route to the matching diagnostic skill. | ||
|
|
||
| If they need to capture a pickle on Ascend NPU first, hand off to | ||
| `pt-snap-ascend-npu-collect` instead of importing. | ||
|
|
||
| ### `pt-snap` missing | ||
|
|
||
| Hand off to `pt-snap-setup`. That skill owns interpreter selection, ownership | ||
| checks, and install approval. This helper must not run `pip` or assume Conda. | ||
|
|
||
| ### Need Ascend NPU collection | ||
|
|
||
| Hand off to `pt-snap-ascend-npu-collect`. Collection ends when a pickle exists | ||
| on disk. It does not import or diagnose. | ||
|
|
||
| ## Boundaries | ||
|
|
||
| - Keep this skill read-only. Do not install Python packages, and do not write files. | ||
| - Do not run `pt-snap skill install` / `upgrade` / `uninstall`. | ||
| - Do not persist focus or edit configuration. | ||
| - Do not start leak, peak, fragmentation, or OOM-root-cause analysis here. | ||
| - Do not classify allocations or allocator gaps. | ||
| - Use the five skill names above exactly; do not invent aliases. | ||
|
|
||
| ## Output | ||
|
|
||
| Report: | ||
|
|
||
| - `Goal` | ||
| - `Input type` (`snapshotdb`, `pickle`, `missing-cli`, or `npu-collect`) | ||
| - `Needed skills` and their `pt-snap skill list --json` status when available | ||
| - `Next skill` (one of the five names) | ||
| - `Install/restart notes` when a skill is missing or outdated | ||
| - `Trusted import notes` when the user only has pickle | ||
| - `Unknowns` | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.