Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ that local environment is intentionally available.

| Surface | Entry point | Responsibility |
| --- | --- | --- |
| CLI | `src/pt_snap_cli/cli.py` via `pt_snap_cli.cli:_safe_call` | Typer commands for focus, import, split, metadata, query, reports, and config |
| CLI | `src/pt_snap_cli/cli.py` via `pt_snap_cli.cli:_safe_call` | Typer commands for focus, import, split, metadata, query, reports, config, and skill install/list |
| Python API | `src/pt_snap_cli/api.py` (`SnapshotAnalyzer`) | Programmatic focus, query, and metadata facade |
| MCP | `src/pt_snap_cli/mcp/server.py` via `pt_snap_cli.mcp.server:main` | Agent tools/resources backed by `SnapshotAnalyzer` |
| Product services | `src/pt_snap_cli/core/` | Shared focus, import, split, query, report, metadata, and error semantics |
Expand Down Expand Up @@ -85,6 +85,20 @@ templates under category subdirectories are included by
executor, `core/query_service.py`, CLI/MCP presentation, and focused tests
together.

### Agent skills

- Author skills under `skills/<name>/SKILL.md`. Keep the packaged copy at
`src/pt_snap_cli/bundled_skills/<name>/SKILL.md` identical so wheel installs
can run `pt-snap skill install`.
- `SkillService` prefers `PT_SNAP_SKILLS_DIR` when set, then the repository
`skills/` tree in a source checkout, then packaged copies. Default install writes the shared
`~/.agents/skills` tree (Cursor, OpenCode, current Codex, and other
Agent Skills hosts) plus Claude's independent `~/.claude/skills` or
`$CLAUDE_CONFIG_DIR/skills`. `--target cursor` and `--target codex` keep
the host-native extras; `--dir` covers anything else. List reports
`installed`, `outdated`, or `missing`. Skill management is CLI-only and
is not exposed on the MCP server.

### Snapshot import and split

- Pickle input is trusted-code execution, not a sandbox. Never load an
Expand Down Expand Up @@ -112,6 +126,7 @@ templates under category subdirectories are included by
| Snapshot import or metadata | `src/pt_snap_cli/core/import_service.py`, `src/pt_snap_cli/core/import_metadata.py`, `src/pt_snap_cli/core/snapshot_import_backend.py` | `tests/core/test_import_*.py`, `tests/test_snapshot_db.py` |
| Snapshot splitting or replay | `src/pt_snap_cli/core/split_service.py`, `src/pt_snap_cli/snapshot/` | `tests/core/test_split_service.py`, `tests/snapshot/` |
| Reports | `src/pt_snap_cli/core/report_service.py`, report commands in `src/pt_snap_cli/cli.py` | `tests/core/test_report_service.py`, report cases in `tests/test_cli.py` |
| Skill list/install destinations or catalog packaging | `src/pt_snap_cli/core/skill_service.py`, `src/pt_snap_cli/bundled_skills/`, skill commands in `src/pt_snap_cli/cli.py` | `tests/core/test_skill_service.py`, `tests/test_bundled_skills.py`, skill cases in `tests/test_cli.py` |
| Agent setup, Ascend NPU collection, diagnostics, or skill evaluation | `skills/`, `tests/skills/`, and the referenced CLI/query surfaces | `tests/skills/` |
| Packaging or release | `pyproject.toml`, `.github/workflows/` | `tests/test_package.py`, `tests/test_release_workflow.py` |
| Executable fixtures | `tests/fixtures/snapshots/` | `tests/test_fixture_provenance.py` before any deserializing suite |
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
| `pt-snap query` | Run memory analysis queries |
| `pt-snap report` | Generate higher-level memory analysis reports |
| `pt-snap config` | Manage global configuration |
| `pt-snap skill` | List and install bundled agent skills |
| `pt-snap-mcp` | Start the MCP server for agent integration |

## MCP Server
Expand All @@ -86,6 +87,7 @@ See the [documentation index](docs/README.md) for all English and Chinese guides
| Managing focus | [Focus Management](docs/en/focus-management.md) |
| Running queries | [Querying](docs/en/querying.md) |
| Splitting snapshots | [Splitting Snapshots](docs/en/splitting.md) |
| Agent skills | [Agent Skills](docs/en/skills.md) |
| MCP server | [MCP Guide](docs/en/mcp.md) |
| Database format | [SnapshotDB Schema](docs/en/database.md) |
| Python API | [SnapshotAnalyzer API](docs/en/snapshot-analyzer-api.md) |
Expand Down
2 changes: 2 additions & 0 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ pt-snap split snapshot.pkl --slices 4 --output snapshot-slices
| `pt-snap query` | 运行内存分析查询 |
| `pt-snap report` | 生成高层内存分析报告 |
| `pt-snap config` | 管理全局配置 |
| `pt-snap skill` | 列出并安装随包 agent skill |
| `pt-snap-mcp` | 启动 MCP 服务器以支持 Agent 集成 |

## MCP 服务器
Expand All @@ -81,6 +82,7 @@ pt-snap-mcp
| Focus 管理 | [Focus Management](docs/zh/focus-management.md) |
| 运行查询 | [Querying](docs/zh/querying.md) |
| 拆分快照 | [拆分快照](docs/zh/splitting.md) |
| Agent skill | [Agent Skills](docs/zh/skills.md) |
| MCP 服务器 | [MCP 指南](docs/zh/mcp.md) |
| 数据库格式 | [SnapshotDB Schema](docs/zh/database.md) |
| Python API | [SnapshotAnalyzer API](docs/zh/snapshot-analyzer-api.md) |
Expand Down
4 changes: 2 additions & 2 deletions docs/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
# docs

## Purpose
`docs` contains end-user and API documentation for the CLI, focus management, query templates, MCP integration, snapshot database format, high-level and result mapping Python APIs, and retained legal evidence. It is split into English and Chinese language trees with a top-level README for navigation.
`docs` contains end-user and API documentation for the CLI, focus management, query templates, agent skills, MCP integration, snapshot database format, high-level and result mapping Python APIs, and retained legal evidence. It is split into English and Chinese language trees with a top-level README for navigation.

## Key Files
| File | Description |
Expand All @@ -30,7 +30,7 @@
- If examples depend on behavior changes, run the matching CLI or service tests.

### Common Patterns
- The two language trees mirror the same topics: quick start, focus management, querying, snapshot splitting, MCP, database schema, SnapshotAnalyzer API, and result mapper API.
- The two language trees mirror the same topics: quick start, focus management, querying, snapshot splitting, agent skills, MCP, database schema, SnapshotAnalyzer API, and result mapper API.

## Dependencies

Expand Down
2 changes: 2 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
| Querying | [en/querying.md](en/querying.md) |
| Reports | [en/querying.md](en/querying.md) |
| Splitting Snapshots | [en/splitting.md](en/splitting.md) |
| Agent skills | [en/skills.md](en/skills.md) |
| MCP server | [en/mcp.md](en/mcp.md) |
| Database Schema | [en/database.md](en/database.md) |
| Import metadata | [en/database.md](en/database.md) |
Expand All @@ -26,6 +27,7 @@
| 运行查询 | [zh/querying.md](zh/querying.md) |
| 分析报告 | [zh/querying.md](zh/querying.md) |
| 拆分快照 | [zh/splitting.md](zh/splitting.md) |
| Agent skill | [zh/skills.md](zh/skills.md) |
| MCP 服务器 | [zh/mcp.md](zh/mcp.md) |
| 数据库格式 | [zh/database.md](zh/database.md) |
| 导入 metadata | [zh/database.md](zh/database.md) |
Expand Down
4 changes: 3 additions & 1 deletion docs/en/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
# en

## Purpose
`docs/en` contains the English documentation set for installing and using `pt-snap-cli`, managing focus, querying and splitting snapshots, running the MCP server, understanding the SQLite schema, and using the high-level and result mapping Python APIs.
`docs/en` contains the English documentation set for installing and using `pt-snap-cli`, managing focus, querying and splitting snapshots, installing bundled agent skills, running the MCP server, understanding the SQLite schema, and using the high-level and result mapping Python APIs.

## Key Files
| File | Description |
Expand All @@ -13,6 +13,7 @@
| `focus-management.md` | Focus resolution, project focus files, environment variables, and global config behavior. |
| `querying.md` | Query listing, template info, parameter usage, result limits, and built-in templates. |
| `splitting.md` | Snapshot slicing strategies, output formats, replay validation, and publication guarantees. |
| `skills.md` | Bundled agent-skill listing, install destinations, and status meanings. |
| `mcp.md` | MCP server setup, tools, resources, prompts, and agent usage. |
| `database.md` | Snapshot SQLite table/schema reference. |
| `snapshot-analyzer-api.md` | High-level Python API for focus, template discovery, queries, and import metadata. |
Expand All @@ -35,6 +36,7 @@

### Common Patterns
- Topic files correspond to major product areas rather than source modules.
- `skills.md` documents `pt-snap skill list` / `install` / `upgrade` / `uninstall`, built-in and `--dir` destinations, and must stay aligned with `SkillService`.

## Dependencies

Expand Down
1 change: 1 addition & 0 deletions docs/en/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,7 @@ pt-snap query --template-use block --device 0 --params '{"min_size": 1048576}'
- [Focus Management](focus-management.md) — Learn how to manage database and device focus across projects and sessions
- [Querying](querying.md) — Query workflows, template discovery, parameters, and output
- [Splitting Snapshots](splitting.md) — Create independently replayable per-device slices
- [Agent Skills](skills.md) — Install bundled agent workflows into the shared agents directory and Claude
- [MCP Server](mcp.md) — Use the MCP server for AI agent integration
- [Database Schema](database.md) — Understand the SnapshotDB format
- [SnapshotAnalyzer API](snapshot-analyzer-api.md) — Query SnapshotDB files from Python
88 changes: 88 additions & 0 deletions docs/en/skills.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Agent Skills

[中文](../zh/skills.md) | English

`pt-snap-cli` ships agent skills for setup, Ascend NPU collection, and memory diagnostics. The `pt-snap skill` commands copy those skills into the shared Agent Skills directory and into host-specific directories that Claude Code still requires.

## List skills

```bash
pt-snap skill list
pt-snap skill list --json
pt-snap skill list --target claude --user
```

Each bundled skill is shown as its own block: name, status, install locations, and a short description. Status is one of:

- `installed` — a matching copy is present in at least one inspected location
- `outdated` — a copy exists but differs from the bundled skill
- `missing` — no copy was found

`--target` accepts a comma-separated list of `agents`, `claude`, `cursor`, and `codex`. `--user` and `--project` limit the scan to user-level or project-local directories. Without those flags, `list` inspects both scopes.

## Destinations

Cursor, OpenCode, Codex, and several other Agent Skills hosts read the shared directories. Claude Code does not; it only reads its own tree. The same commands work on Windows, macOS, and Linux because the CLI uses `Path.home()`.

| `--target` | User directory | Project directory | Who reads it |
|------------|----------------|-------------------|--------------|
| `agents` (default) | `~/.agents/skills` | `.agents/skills` | Cursor, OpenCode, Codex (current official user/repo path), Cline, and other Agent Skills hosts |
| `claude` (default) | `~/.claude/skills` | `.claude/skills` | Claude Code. Cursor and OpenCode also load this tree for compatibility. |
| `cursor` | `~/.cursor/skills` | `.cursor/skills` | Cursor-native extra. Cloud Agents sync only this user directory, not `~/.agents/skills`. |
| `codex` | `~/.codex/skills` | `.codex/skills` | Codex legacy user home (`$CODEX_HOME/skills`). Codex still scans it; new user skills belong in `agents`. |

Windows equivalents use `%USERPROFILE%` instead of `~`. If `CLAUDE_CONFIG_DIR` is set, user-level Claude skills go to `$CLAUDE_CONFIG_DIR/skills`. If `CODEX_HOME` is set, `--target codex` writes `$CODEX_HOME/skills`. Set `PT_SNAP_SKILLS_DIR` to a directory of `*/SKILL.md` folders to load a custom catalog instead of the repository `skills/` tree or the packaged copies; it does not change install destinations.

OpenCode also has a native tree at `~/.config/opencode/skills` and `.opencode/skills`. It already reads `agents` and `claude`, so a separate OpenCode target is not required. Use `--dir` for that native tree, Windsurf, or any other custom folder. `--dir` cannot be combined with `--target`, `--user`, or `--project`.

```bash
pt-snap skill install --dir C:\Users\you\custom-skills
pt-snap skill list --dir C:\Users\you\custom-skills
pt-snap skill upgrade --dir C:\Users\you\custom-skills
pt-snap skill uninstall --dir C:\Users\you\custom-skills
```

## Install skills

```bash
pt-snap skill install
pt-snap skill install pt-snap-setup --target claude
pt-snap skill install --project --target agents
```

Omitting skill names installs every bundled skill. The default destination is the shared user-level `agents` directory plus Claude. Use `--target` to choose hosts, `--project` to write into the current working directory, or `--dir` for a custom skills folder.

If a destination already exists and its contents differ, install refuses unless you pass `--force`. Identical copies are left unchanged. When more than one host is selected, every destination is checked before any copy is written.

## Upgrade skills

```bash
pt-snap skill upgrade
pt-snap skill upgrade pt-snap-setup --target claude
```

`upgrade` replaces outdated copies that already contain `SKILL.md`. Missing skills are left missing; current copies are left unchanged. A same-named path that exists without `SKILL.md` is left untouched; use `install --force` to replace it.

## Uninstall skills

```bash
pt-snap skill uninstall
pt-snap skill uninstall pt-snap-setup --target claude
pt-snap skill uninstall --project --target cursor
```

`uninstall` removes bundled skill directories that contain `SKILL.md`. Skills that are not installed are reported as `not_installed`. A same-named path that exists without `SKILL.md` is left untouched.

After an install, upgrade, or uninstall that changes skill files, restart the agent so it picks up the change.

## Bundled skills

| Skill | Use when |
|-------|----------|
| `pt-snap-setup` | Installing or verifying `pt-snap-cli` in the active Python environment |
| `pt-snap-ascend-npu-collect` | Collecting an Ascend NPU memory snapshot pickle |
| `pt-snap-memory-leak` | Diagnosing live allocations and leak candidates in a SnapshotDB |
| `pt-snap-memory-peak-breakdown` | Explaining active memory at a peak event |
| `pt-snap-memory-fragmentation` | Diagnosing allocator gaps and reserved-pool pressure |

Skill management is CLI-only. The MCP server does not install, upgrade, or uninstall skills.
4 changes: 3 additions & 1 deletion docs/zh/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
# zh

## Purpose
`docs/zh` contains the Chinese documentation set for `pt-snap-cli`, covering the same user-facing areas as the English docs: quick start, focus management, querying, snapshot splitting, MCP integration, database schema, and the high-level and result mapping Python APIs.
`docs/zh` contains the Chinese documentation set for `pt-snap-cli`, covering the same user-facing areas as the English docs: quick start, focus management, querying, snapshot splitting, agent skills, MCP integration, database schema, and the high-level and result mapping Python APIs.

## Key Files
| File | Description |
Expand All @@ -13,6 +13,7 @@
| `focus-management.md` | Chinese guide to focus resolution and persistence. |
| `querying.md` | Chinese guide to query templates, parameters, and output. |
| `splitting.md` | Chinese guide to snapshot slicing, formats, replay validation, and publication. |
| `skills.md` | Chinese guide to bundled agent-skill listing and installation. |
| `mcp.md` | Chinese MCP server setup and tool reference. |
| `database.md` | Chinese snapshot SQLite schema reference. |
| `snapshot-analyzer-api.md` | Chinese guide to the high-level focus, query, and metadata Python API. |
Expand All @@ -34,6 +35,7 @@

### Common Patterns
- Files mirror the English documentation topics one-for-one.
- `skills.md` must stay aligned with `../en/skills.md` and `SkillService`.

## Dependencies

Expand Down
1 change: 1 addition & 0 deletions docs/zh/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@ pt-snap query --template-use block --device 0 --params '{"min_size": 1048576}'
- [Focus 管理](focus-management.md) — 学习如何在多个项目和会话之间管理数据库和设备焦点
- [运行查询](querying.md) — 查询流程、模板发现、参数和输出说明
- [拆分快照](splitting.md) — 创建可独立回放的逐设备切片
- [Agent Skills](skills.md) — 将随包 agent 工作流安装到共享 agents 目录和 Claude
- [MCP 服务器](mcp.md) — 使用 MCP 服务器进行 AI Agent 集成
- [数据库格式](database.md) — 了解 SnapshotDB 格式
- [SnapshotAnalyzer API](snapshot-analyzer-api.md) — 从 Python 查询 SnapshotDB 文件
Loading
Loading