SKILL.md agent-dispatch refs (`agents/<name>.md`) don't match install path and don't name the registered subagent_type → deterministic extract-structure pass gets skipped

[MrAladdin]

Summary

The SKILL.md agent-dispatch instructions point to agents/<name>.md as a path relative to the skill, but that path doesn't exist at the installed location — the agent files live at the plugin root agents/, not skills/understand/agents/. Combined with not naming the registered subagent_type, this leads an executing agent to either fail to find the file or fall back to a general-purpose subagent with a hand-built prompt — silently skipping file-analyzer's built-in two-phase work (the deterministic extract-structure.mjs tree-sitter pass), which produces lower-quality, drift-prone nodes/edges.

Evidence (plugin v2.7.7, Claude Code install)

SKILL.md repeats this phrasing for every phase, e.g. line 309:

For each batch, dispatch a subagent using the file-analyzer agent definition (at agents/file-analyzer.md).

But at the installed path:

$ ls .../skills/understand/agents/file-analyzer.md
No such file or directory          # the relative path in SKILL.md resolves here

$ ls .../agents/file-analyzer.md
.../agents/file-analyzer.md        # actually lives at the PLUGIN ROOT

And the agents are registered as Claude Code plugin agents (understand-anything:file-analyzer, :project-scanner, etc.) — directly dispatchable via the Task tool's subagent_type.

So agents/file-analyzer.md:

1. Is not where the relative path says (plugin-root agents/, not the skill dir). SKILL.md itself acknowledges plugin-root resolution is non-trivial (the Preamble has a whole plugin-root detection block), yet the agent references stay as bare agents/....
2. Doesn't say how to "use" it — read-the-file-into-a-prompt vs. dispatch the registered agent type are very different, and only the latter triggers the two-phase deterministic extraction.

Impact

An executor that takes the path literally finds nothing, then improvises a general-purpose subagent. That subagent has no knowledge of extract-structure.mjs, so Phase 2 emits LLM-derived structure directly — slower, token-heavy, and prone to analyzing the wrong files. (This is the actual mechanism behind several "agents drift / low-quality graph" reports such as #460/#384, when the deterministic path is bypassed.)

Suggested fix

Make dispatch unambiguous in SKILL.md — name the registered agent type instead of (or in addition to) a relative file path. For each phase that dispatches, e.g.:

Dispatch via the Task tool with subagent_type: understand-anything:file-analyzer (a registered plugin agent). [If your host can't dispatch by name, load the definition from the plugin-root agents/file-analyzer.md — note it's at the plugin root, resolved per the Preamble's plugin-root logic, not skills/understand/agents/.]

This removes the path mismatch and the read-vs-dispatch ambiguity, ensuring the deterministic extract-structure.mjs pass actually runs.

Environment

• Plugin 2.7.7, Claude Code (/plugin install understand-anything), macOS.

[Lum1104]

I see, that make sense, thanks!