fix(cli): agent init ships a 164-line skill surface that routes to skills it never installs — agents never found doctor, otel or logs

[rickylabs]

netscript agent init installs a skill surface that routes agents to skills it does not install, and is too thin to make them competent at diagnosing Deno or Aspire problems. Measured against a five-agent build round, the consequences are concrete.

The routing dead end

The installed netscript skill describes itself as a router:

DO NOT USE FOR: generic Deno language/tooling questions (use the Deno docs); Aspire orchestration, dashboards, or resource graph specifics (use the aspire skill)

agent init does not install an aspire skill. It installs exactly three: netscript (36 lines), netscript-build (66), netscript-operate (62) — 164 lines total. An agent that follows the router's own instruction for an Aspire problem finds nothing.

Meanwhile the repository maintains, and does not ship:

skill	lines
deno-fresh	956
netscript-tools	191
netscript-cli	154
netscript-deno-toolchain	118
aspire	105

1,524 lines of relevant material exists and never reaches a consumer project.

What it cost — measured, not hypothesised

Across five agents building real products on 0.0.2 for a day each:

capability	times used
netscript plugin doctor	0
aspire otel (logs / spans / traces)	0
aspire export	0
aspire ps	2
hand-rolled curl probing	5 drift reports

netscript plugin doctor is mentioned six times in the installed skills, including netscript-operate/SKILL.md:57 — "Prefer doctor for setup problems over hand-probing endpoints." Every agent hand-probed endpoints instead.

That is the important part: a mention in a capability table is not enough to change behaviour. The commands are named but never attached to the symptom that should trigger them, so an agent under pressure reaches for what it already knows — curl, retries, guesswork.

Real consequences from that round, all independently verified:

• Four agents trusted Aspire's Healthy label against an endpoint that timed out on every request (fix(aspire): executable resources report Healthy without an endpoint readiness check #1012). One aspire logs or aspire otel logs would have ended it.
• Three agents fought Playwright/Chrome hangs to read browser console output that Aspire already captures by default via withBrowserLogs().
• aspire restore was reported as stalling 10–50 minutes; clean-room time is 2.6 s. Nobody had the means to distinguish environment from defect.
• Type failures were chased without deno check on the specific file or deno info to see how a module actually resolved.

What should ship

1. An aspire skill — the router already promises it. Diagnostic-first: aspire logs, aspire otel logs|spans|traces, aspire describe --format Json (including that healthStatus: Healthy with empty healthReports means nothing was checked), aspire ps, aspire resource <r> restart, aspire doctor, aspire export.
2. A deno skill — runtime/toolchain diagnostics, distinct from the Fresh-specific deno-fresh: deno check on a single file, deno info for resolution, permissions, cache/--reload, test sanitizers, and the exit-code/pipe trap.
3. A help.md troubleshooting playbook, organised by symptom rather than by command, so the right tool is reachable from the situation an agent is actually in: dangling AppHost → aspire stop --all; Vite hanging → aspire resource <r> restart; an event never fires → aspire otel traces; need the browser console → it is already in Aspire; unsure about an API → deno doc first, then the docs via MCP.
4. The AGENTS.md block that agent init writes must mandate all of them. It currently reads only "Use the installed NetScript skills and MCP server for framework-aware build, diagnostics, and operations" — no mention of Deno or Aspire competence.

Acceptance criteria

• netscript agent init installs an aspire skill and a deno skill alongside the existing NetScript skills.
• No installed skill routes to a skill that agent init does not install.
• A symptom-indexed troubleshooting document ships with them.
• The AGENTS.md/CLAUDE.md block written by agent init names all installed skills and directs agents to the Aspire and Deno ones for orchestration and runtime problems respectively.
• The skills surface netscript plugin doctor, aspire otel, aspire logs and deno info from the symptom, not only in a capability table.
• Test: after netscript agent init, every skill referenced by an installed skill's routing description resolves to an installed skill.