SKILL.md · 24000
n approval and only ever lists public, unauthenticated
tools. Offer it once tools are integrated; build it per references/discovery.md.
Record the approval before writing any file in pipeline.discovery (at,
publishedTools, paths: [], complete: false) — that's what survives a context
reset and what lets AUDIT map these hunks. Append each artifact to paths as you
write it and set complete: true only once every artifact exists and its drift
test passes. Approved but complete: false is unfinished work: finish it before
leaving INTEGRATE — otherwise a reset mid-publication looks exactly like a
finished one. pipeline.discovery: null means not approved: never create or update
a published manifest, and flag one the pipeline created or modified since
baselineSha as an unmapped hunk (a pre-existing, untouched manifest is not your
hunk — leave it alone).
Optional — WORKBENCH (visual inspection)
When the user asks to inspect or try tools visually, read
references/workbench.md and launch the temporary Workbench yourself. Prefer its
Playwright runner: it injects before application code, requires no extension,
flag, command, or project edit from the user, and cleans up when the browser
closes. The panel must visibly say Native or Simulated. Obtain separate user
approval before installing Playwright or downloading a browser (interactive default
No; noninteractive flags and their exact scope are in references/workbench.md).
Never install dependencies without approval.
Workbench is read-only: only observed, non-excluded tools with approved manifest
mutating: false may run, in either transport. Simulated transport calls real
handlers and does not make them side-effect-free. Client/server/unknown mutations
must use a supported host journal runner; Workbench has no mutation override.
On Windows without flock/lockf, or any unsupported locking host, perform only
read-only inventory/checks and report mutation checks not-run until a supported
host runner is available. Never bypass locking or install dependencies to bypass it.
Use the approved manifest as Expected evidence and the live page as Observed
evidence. Simulated mode is useful for portable browser/device and responsive
checks, but never changes a tool to verified; the normal headed native-browser
loop below remains authoritative. Never ship Workbench in a production entry or
bundle. If a physical device requires temporary dev-entry wiring, the agent adds
and removes it within the same inspection session.
Phase 3 — VERIFY (loop)
Set up once from templates/webmcp.spec.ts plus the shipped host-side
templates/mutation-journal.{ts,js} per references/verify.md (real headed Chrome;
current production document.modelContext.getTools()/executeTool() surface).
Before any execution, enforce the durable mutation journal in
references/reverify.md: scan unresolved attempts, persist each mutation before
dispatch, and settle only after independent reconciliation and cleanup. Use its
hooks in the chosen runner; without them, mutations are blocked.
Then loop over every integrated tool, using its manifest route, auth,
examples, expect, and annotations fields:
- assert the tool is registered with the expected schema (enumerated
inputSchemais a stringified JSON Schema — parse before comparing) and the manifestannotations; - execute the valid example (mutating tools: dev/test data only, then run
cleanup) and one invalid example (invalid: nullzero-param read tools: dual-outcome assertion — seereferences/verify.md); - assert on the returned structured result and the resulting UI state per
expect; for route actions, assertexpect.navigationafter the deferred app navigation. A bare imperativenull/undefinedresult is a failure.
Pass → "verified". Fail → "failed" + failure note. Role-scoped tools: run the
loop once per role listed in auth, signing in via the matching
app.authFixtures entry.
Production side-effect policy — when a tool's verification unavoidably causes
a real production effect (e.g. an email actually sent), ALL THREE are required:
(1) the human approved it at the gate, recorded in approval.productionSideEffect;
(2) every test payload is marked [webmcpify verification]; (3) the effect is
listed in report.md. Without the recorded approval, don't execute the live
path — mark the tool skipped with a blocker note.
Phase 4 — HEAL (loop)
Preserve and reconcile mutation journal entries before every retry; a failure
status or contract revision never clears uncertain execution.
While any tool is "failed": diagnose via references/heal.md, fix only that
tool's integration — implementation-only fixes; if the fix would change the
approved contract (schema, description, mutating class, annotations,
expect), go back to the gate for re-approval instead of silently changing the
manifest. Classify the failure before counting it. attempts counts only
independent retries of the same failure signature under the same contract revision;
environment and shared contract failures do not burn one attempt on every affected
tool. When the contract changes after re-approval, increment contractRevision,
clear failure, and reset attempts. At three independent failed retries of an
unchanged implementation/flaky signature, "skipped" requires the failure class,
signature, and evidence that makes the tool impossible under the current contract.
Never widen the diff or fake a pass. After healing, re-run verification once for all tools
with status integrated or verified (healing one tool can break another —
scope collisions).
Exit: every tool is verified, skipped, or rejected; build green.
Final — AUDIT + report
- Diff audit (flag-only, never auto-revert): collect the pipeline's changes —
git diff <baselineSha>..HEADplus the index and untracked files undercommit-per-batch, or the working tree + index + untracked underno-commit. Every hunk must map to a manifest entry, a recordedpipeline.setuppath, or apipeline.discovery.pathsentry. An unmapped hunk → flag it in the report with file/line and a suggested disposition; never revert anything yourself. A hunk in abaselineDirtyfile → untouchable, flag only. Without abaselineSha, audit the files named in manifestsourcefields,pipeline.setuppaths, andpipeline.discovery.paths(setup entries recorded asnullby the v2→v3 migration: fall back to flag-only for those files). - Finalize
.webmcpify/report.md: the enumerated route→tool map, coverage target, tool coverage per area, skipped/rejected tools with reasons, security notes (which mutating tools exist, what guards them, any recorded production side effects), how to test manually (flag, DevTools WebMCP pane, inspector extension), and every blocker that needs a human. - Tell the human: what's exposed, what's skipped and why, and how to try it.
References (read on demand, not upfront)
references/inventory.md— area mapping, naming/schema conventions, budgets/overlapreferences/integrate.md— declarative + imperative patterns per stackreferences/runtime.md— vendoring + wiring thetemplates/runtimereferences/workbench.md— read-only visual inspection, dependency consent, and evidence modesreferences/verify.md— harness setup: flags, surfaces, Playwright/Puppeteer, evalsreferences/heal.md— failure taxonomy → fixesreferences/discovery.md— optional off-page discovery (manifest,rel="webmcp",llms.txt) + how to read third-party audit scoresreferences/security.md— the security checklist (apply before the gate and at audit)