feat(skill): steer localExplorer to structured cluster tool over raw CLI - #21
Conversation
local-exploration-workflow step 4 now distinguishes local-node visibility (nvidia-smi/free/df — shell) from cluster-scheduler state (capacity, jobs, status/logs). For the latter it tells the worker to prefer a structured cluster tool *if its catalog includes one*, falling back to shell otherwise. Catalog-relative by design: BrainppCluster is driver-gated (requiresDriver: 'brainpp') and only renders under runtime.driver === 'brainpp', so the static skill body must not name it — the "if your tool catalog includes" phrasing self-nullifies in non-brainpp deployments (Local/Docker/other driver) instead of dangling a reference to a tool that isn't there. Motivated by a dogfood where localExplorer had BrainppCluster inline on the wire (13 turns) yet probed brainctl/rlaunch via Bash throughout. Local- visibility recon via shell stays correct; this only redirects genuine cluster-scheduler queries to the structured tool. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
✅ Ready to approve
The change is a low-risk, consistent update to skill prose plus its regenerated bundle output, with no functional code-path modifications.
Note: this review does not count toward required approvals for merging.
Pull request overview
This PR updates the bundled local-exploration-workflow skill guidance so that when an agent needs cluster-level scheduler/state information, it prefers an available structured cluster tool from the tool catalog over parsing raw CLI output, while keeping node/container-local probes (e.g., nvidia-smi, free, df) as shell-based.
Changes:
- Extend step 4 of
local-exploration-workflowto explicitly separate node/container visibility probes from cluster-scheduler probes and recommend structured tools when present. - Regenerate bundled skill output so
index.generated.tsreflects the updated SKILL.md body.
File summaries
| File | Description |
|---|---|
| src/skill/bundled/local-exploration-workflow/SKILL.md | Adds guidance to prefer structured cluster tools for scheduler/state queries while keeping local system probes in shell. |
| src/skill/bundled/index.generated.ts | Updates the generated bundled skill body to match the modified SKILL.md content. |
Copilot's findings
- Files reviewed: 2/2 changed files
- Comments generated: 0
Note
Your feedback helps us improve the quality of this feature.
Please use 👍 or 👎 to tell us whether this assessment is correct.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: abc6efc4a8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 2. The framework injects relevant prior memory automatically — check it first; you may already have a pointer to the answer (e.g. a previously-noted file path) without searching. But memory is a hint, not a fact (see #3). | ||
| 3. Verify memory-derived assumptions before relying on them. The local environment changes — files move, packages upgrade, configs relocate. If memory says "config X is at /etc/x.conf", probe it (a quick stat) to confirm before quoting it as the answer. Memory shortens the lookup path; it does not skip verification. | ||
| 4. Pick the right probe for the scope: pattern search in files, file lookup by glob, full-file read for known paths, shell commands for system state (process tree, env, disk, package metadata, log tails). | ||
| 4. Pick the right probe for the scope: pattern search in files, file lookup by glob, full-file read for known paths, shell commands for system state (process tree, env, disk, package metadata, log tails). Distinguish what *this* node/container itself sees (`nvidia-smi`, `free`, `df` — ordinary shell probes) from cluster-scheduler state (pool-wide capacity, queued or running jobs, a job's status or logs): for the latter, if your tool catalog includes a structured cluster tool, prefer it over parsing raw CLI text (e.g. `kubectl` / `squeue`), and fall back to shell only when no such tool is present. |
There was a problem hiding this comment.
This changes the localExplorer skill body that is inlined into rendered role prompts, but the prompt snapshot expectations were not updated: both src/agents/role-prompt.snapshot.test.ts and src/prompt/prompt-for-role.test.ts still pin the old localExplorer hash (05c146...). In CI with dependencies installed, the localExplorer assertion in those snapshot tests will fail until the expected hashes/change log are regenerated for this prompt text change.
Useful? React with 👍 / 👎.
背景
Dogfood 复盘:main 派发 localExplorer 做 vLLM 部署前的只读集群侦察,worker 全程用裸
brainctl/rlaunch探,没用结构化的BrainppCluster工具。wire 实证(api-log)显示BrainppCluster完整 schema 13 轮都 inline 在工具表里、直接可调(dispatched worker 走 systemPromptOverride 路径,deferred 关闭、无需 ToolSearch),但local-exploration-workflow正文从未提示"集群状态优先用结构化工具",模型就默认 reach for Bash 了。改动
local-exploration-workflowstep 4 加一句,把两类问题分开:nvidia-smi/free/df)→ 仍走 shell(这次任务的正确做法,不被推翻);关键设计:catalog-relative,不硬点工具名
BrainppCluster带requiresDriver:'brainpp',只在runtime.driver === 'brainpp'时渲染。skill 正文是环境无关的静态文本,所以不能硬写BrainppCluster——否则在非 brainpp 部署(Local/Docker/其它 driver)里会指着一个不存在的工具。改用 "if your tool catalog includes a structured cluster tool" 的现象学措辞:工具在就用、不在整句自动作废。CLI 例子也从罕见的brainctl/rlaunch换成通用的kubectl/squeue。全仓审计确认
BrainppCluster是唯一的requiresDriver工具,且没有任何 skill 正文硬点过条件渲染工具名——同类隐患仅此一处。验证
pnpm gen:skills重生成index.generated.ts(已含新文案)pnpm typecheck通过生效需 daemon rebuild + restart。
🤖 Generated with Claude Code