agenticschema: Skill for Claude Code

WebMCP Tool Development Workflow (build-webmcp-tools)

WebMCP lets a web page expose client-side capabilities as structured tools to in-browser AI agents on document.modelContext, instead of agents scraping or clicking the DOM. This skill routes a developer to the right stage of the tool lifecycle and points to the reference file that holds the detailed rules and code for that stage.

Key tenet: WebMCP runs client-side in the browser tab on document.modelContext, inside the user's authenticated session. It supports Tools only (no Resources or Prompts). It is not a backend MCP server over stdio/SSE, and tools execute application logic (state stores, APIs, client routers) directly rather than simulating typing or clicks.

How to Use This Skill

1. Match the developer's request to a row in the Router and go to that stage.
2. Read the files in the "Read first" column before responding. Paths are relative to this skill's directory. This file only summarizes them; the detailed rules, examples, and code patterns live in the references, so do not answer from this summary alone.
3. If the request refers to an artifact you were not given (transcripts, schema.json, source files), read it if it is available in the workspace; otherwise ask for it, and outline how you will apply the stage's key rules from its reference file (for audits, include the verification steps). Never invent the missing artifact.
4. Apply the Non-Negotiables to everything you produce.
5. Before finishing an audit, schema.json, or implementation, check your output against references/audit-checklist.md.

Non-Negotiables

• Budgets: tool and parameter names ≤ 30 chars; tool descriptions ≤ 500 chars; parameter descriptions ≤ 150 chars; output ≤ 1,500 chars (~400 tokens), paginated. → tool-design.md
• Descriptions: "What + When" (what the tool does, when to choose it); never repeat inputSchema parameters; no implementation jargon (Redux, Pinia, Express, REST, GraphQL, gRPC). → tool-design.md
• Naming & shape: action verbs; initiate_* for tools that open a form or wizard vs. book_*/create_* for immediate execution; never make the model compute values (relative dates, conversions): accept the user's phrasing and resolve it in the app, though unambiguous lookups to standard codes are fine; prefer names over opaque IDs; recommended: consolidate entities that share a lifecycle and annotations into polymorphic, batched tools, keeping trusted and user-authored content in separate tools. → tool-design.md
• Annotations: all hints default to false and are strictly opt-in (specify only when true; never declare : false); readOnlyHint: true only on pure queries; consequentialHint: true only on significant, irreversible real-world actions (payments, bookings, deletions); view navigation, tab switching, and initiate_* hand-offs must not declare readOnlyHint: true (omit it) and do not need consequentialHint, protecting unsaved work inside the tool; routine mutating tools omit annotations; untrustedContentHint: true on any output containing user- or third-party-authored text, even from your own database. → annotations.md
• Errors reach the agent: React useWebMCP throws Error (→ isError: true); native registerTool resolves { error, code, retryable } because rejections become a generic DOMException: UnknownError; declarative forms resolve structured field errors via event.respondWith. → error-handling.md
• UI sync: await state and DOM updates before a tool returns.
• Cross-origin: tools are same-origin by default (Permissions Policy tools, default self); delegate only with <iframe allow="tools"> plus registerTool(tool, { exposedTo: ['https://trusted.origin'] }); origin isolation is required (Origin-Agent-Cluster: ?0 disables WebMCP). → vanilla-patterns.md
• Design before code: every tool goes through Stages 2–4 (starting states, role-play, variations, and critique of tone, clarifying questions, and autonomous boundaries) before Stage 5–6 schemas, evals, or code; implementation simplicity is not conversational simplicity. Run Stages 2–6 in Interactive Mode (pausing after each goal's role-play for developer critique) or Autonomous Mode (working through each isolated goal's Stages 2–4, self-critique, and Stage 5–6 consolidation/code end-to-end without stops). Only skip Stages 2–4 on the Explicit Fast Path below when asked to skip design for one tool. → conversational-design.md