Skill v1.0.0
currentTrusted Publisher100/100version: "1.0.0"
Setup walkthrough
Work top to bottom. Every step has a verification before the next one starts.
1. Keys
| key | where | notes | |
|---|---|---|---|
ANTHROPIC_API_KEY | <https://console.anthropic.com/settings/keys> | or skip it and sign in once with ant auth login. The org needs Managed Agents access | |
NATIONAL_PARK_SERVICE_API_KEY | <https://www.nps.gov/subjects/developer/get-started.htm> | free, emailed instantly | |
WINDY_API_KEY | <https://api.windy.com/point-forecast/docs> | free tier, point-forecast product |
cp .env.example .env.local # then fill in the three keys
Verify the vendor keys from your own machine before involving the sandbox:
curl -sS "https://developer.nps.gov/api/v1/alerts?parkCode=acad&limit=1" -H "X-Api-Key: $NATIONAL_PARK_SERVICE_API_KEY" | head -c 300curl -sS -X POST "https://api.windy.com/api/point-forecast/v2" \-H "Content-Type: application/json" \-d '{"lat":44.35,"lon":-68.21,"model":"gfs","parameters":["temp"],"levels":["surface"],"key":"'"$WINDY_API_KEY"'"}' | head -c 300
Both return JSON. A 403 here is a key problem, not a cookbook problem.
2. Provision
npm installnpm run setup
Creates the environment (networking limited to developer.nps.gov and api.windy.com), the reviewer agent (Opus, review-only prompt), the planner agent (bash on, web_search/web_fetch off, a multiagent coordinator roster naming the reviewer), the vault, and two environment_variable credentials with the injection_location each vendor documents hardcoded (NPS: header, Windy: body). Writes six ROADTRIP_PLANNER_* ids into .env.local. Re-running is a no-op while the agent exists (it does demand --force if the stored planner predates the reviewer roster), and --force provisions a fresh copy.
3. Run
npm run dev
Open <http://localhost:3000>. The page creates one session per browser on load (cookie roadtrip_planner_session_id), so the sandbox is warm before the first question. Then do the four beats in README.md, in order. Beat 2 is the vault story and it only lands after a real conversation exists. Beat 3 is the agent_with_overrides model picker. Beat 4 is the multi-agent review: it needs a full itinerary ask, not a one-fact question.
Debugging
| symptom | cause | fix | |
|---|---|---|---|
npm run setup 404s on /v1/environments | org not enrolled in Managed Agents | request access, or switch orgs | |
tsc rejects event_deltas, injection_location, or the lib/sessions/accumulate import | installed SDK predates the 2026-07-01 Managed Agents update | upgrade @anthropic-ai/sdk | |
| replies arrive whole, no token-by-token rendering | the org's streaming gate is closed (event_deltas is silently ignored when ungated), or an older SDK's stream parser drops the event_start / event_delta events it does not recognize | confirm the org is enrolled in the update; upgrade @anthropic-ai/sdk | |
| picking a model 400s with "Agent must be a non-empty Agent ID or agent_reference" (or the older "Extra inputs are not permitted") | the org's gate for agent_with_overrides is not open yet (a closed gate rejects the selector as an unknown agent shape) | use the default model until the org is enrolled in the update | |
picking a model 400s with agent_field_not_overridable | the selector carried a key that is not overridable (the gate is open; only model, system, tools, mcp_servers, skills may be overridden) | only happens if you edited createTripSession: remove the extra key | |
boot screen says Missing ROADTRIP_PLANNER_AGENT_ID | .env.local not written or dev server started before setup | run npm run setup, restart npm run dev | |
| events arrive only in end-of-turn bursts | a proxy is buffering the SSE response | use next dev directly on localhost first | |
| answer cites no tool calls | the agent answered from priors | the prompt demands API evidence per claim: re-run npm run setup -- --force if you weakened it | |
| itinerary arrives with no review handoff (no thread events in the rail) | the stored planner predates the reviewer roster (provisioned before the multiagent change), or the question was small enough that the prompt's "skip the review" branch applied | re-run npm run setup -- --force; ask for a full multi-day itinerary | |
npm run setup 400s creating the planner, naming multiagent | the org is not enrolled in the Managed Agents update that ships coordinator rosters | use a single-agent copy (delete the multiagent line in setup/create.ts) until the org is enrolled | |
| every NPS call 403s with header injection on | the National Park Service key itself is bad | re-run the step 1 curl from your machine | |
session.error credential_host_unreachable_error | the credential allows a host the environment's networking does not | both allowed_hosts lists must name the vendor host | |
| the chat resets to an empty trip after a teardown | the cookie pointed at an archived session, so a fresh one was created | expected: archived sessions cannot take another message |
Reset
npm run teardown # archive sessions, both agents, vault, credentials, environmentnpm run setup -- --force # provision a fresh copy