[rgarcia]

Summary

Rewrites the kernel-mcp skill around the multi-step flows that span several MCP tools. The old version mostly listed tools, which repeated what each tool's description and the server's instructions already tell the model. The new skill covers order of operations, decision points, and stop/never-retry rules, and refers to tools only by name and action.

Stacked on #49. It edits only skills/kernel-mcp/SKILL.md, regenerates the Grok copy with scripts/sync-plugin-skills.sh, and bumps the Grok plugin to 1.2.0.

New structure

• Before you start: connection scope (get_connection_context, project), which tools are gated (vault tools and web_search by entitlement, open_auth_login by MCP Apps support), the rule that secrets and bearer links stay out of chat, and the 60-second default timeout.
• Pick the tool: a routing table from intent to tool and action.
• Browser sessions: create-only options, the proxy object, names vs ids, profiles, named Playwright executors, pools, and REPL state rules.
• Sites that reject ordinary automated clients: config registry lookup → resolve/get_analysis → apply → submit_feedback.
• Logins: decision first, then Fill from Vault (KERNEL-hosted collection and 1Password brokered approval), passkeys, managed auth, and manual profile capture.
• Payments: wallet connection, Link card at checkout, KERNEL card, agentcard, confirm_transaction, and a stop-rules table.
• WebMCP, files and local services, debugging, apps, reporting.

Factual corrections

• datacenter is not an accepted proxy type. Types are isp, residential, mobile, and custom, with targeting in config.
• proxy_id on manage_browsers is deprecated in favor of proxy: {id|name|mode}.
• manage_auth_connections list filters with domain_filter, must be read across every page, and the user picks when several accounts match.
• A NEEDS_AUTH connection is reauthenticated (open_auth_login mode: "reauth" or login on its id), not recreated.
• wait long-polls for at most 30 seconds and must be called again while pending.
• open_auth_login is preferred when the client supports MCP Apps.
• manage_profiles setup saves the profile only when the setup browser is deleted, and needs update_existing for an existing name.
• Pool release needs id_or_name and session_id. Pooled browsers can't attach vaults. Lease idle timeout defaults to 600 seconds.
• manage_extensions is list/get/delete only. Upload happens outside MCP, and extensions are create-only on a browser.
• manage_replays also has list and returns view URLs. Framerates above 20 need gpu.
• get_telemetry reads deleted sessions only by id, and only for activity captured while telemetry was enabled. Telemetry is off by default and its default categories leave out console, network, and page events.
• browser_repl ignores expression values (output goes through repl.write and friends), and a timeout drops all state.
• The frontmatter description now covers forms, sign-in, payments, and files, matching the server's own description.

Each claim was checked against kernel/kernel-mcp-server main, including vault-cards.ts, vault-wallets.ts, vault-items.ts, vault-credentials.ts, and vault-responses.ts for the payment and vault sections. Rules the source leaves ambiguous were left out.

Login guidance follows the docs

The login section opens with the decision from auth/overview.mdx, auth/fill-from-vault.mdx, and auth/managed-auth.mdx, before either flow's steps:

• Fill from Vault is the default. It fits when authentication appears mid-workflow in the same browser session, when the agent owns navigation, submission, and recovery, or when the caller controls how credentials are requested.
• Managed auth fits when the user wants KERNEL to run login and keep a reusable session healthy (health checks, automatic reauthentication), the task runs unattended or signs in repeatedly, and the user can come back for input. It also says reauthentication isn't guaranteed.

The vault steps mirror vaults/overview.mdx, vaults/fill.mdx, vaults/credentials.mdx, vaults/1password.mdx, and browsers/use-vault-credentials-in-browser-agent.mdx:

• ask the user which credential path they prefer
• a per-user vault attached at browser creation
• the collection URL shared privately
• ready doesn't mean logged in
• fill never submits; retry only after checking the page, never in a loop
• 1Password approval happens in the owner's app

The payment steps follow browsers/payments.mdx: verify the purchase first, and never retry a failed, timed-out, rejected, or indeterminate payment.

Wording

The MCP server will serve this skill, and its tests hold skill prose to its access-language and brand-casing rules. Prose avoids the blocked terms and uses "site-compatibility" and "sites the user is authorized to access". stealth appears only as an API field in code. Prose is lowercase except KERNEL.

Testing

• scripts/sync-plugin-skills.sh --check passes.
• A local check that mirrors the server's blocked-language and casing rules passes on the description and on the body with code removed.
• Generated the server's bundled skills module from this commit on the open skills-extension branch of kernel/kernel-mcp-server. bun test src/lib/mcp/prompts.test.ts src/lib/mcp/skills src/lib/mcp/register.test.ts passes, 18/18. That branch was not modified.
• Not exercised end to end in an MCP client.

[masnwilliams]

LGTM. I checked the claims against kernel-mcp-server main and found no factual errors. The skill also passes the server's blocked-language and casing checks, and sync-plugin-skills.sh --check passes.

Non-blocking suggestions:

• Split by entitlement. Logins and payments are about 60% of the ~3.5k words, and most of that only applies when the vault tools are available. Moving them to references/vault-logins.md and references/payments.md would keep SKILL.md short. Both the skills build and the sync script already handle multi-file skills.
• Parameter-level details repeated from tool descriptions. The payments and vault sections restate details that manage_vault_cards/manage_vault_items/manage_vault_wallets already carry: the 50000 minor-unit cap, 409 after authorize, page_not_found/ambiguous_page, billing_*, and the "can't be updated" rules. The server pins the skill by commit, so these copies can drift from the tool text. Keeping only the ordering and stop rules would avoid that.
• Create-only list. Step 1 under browser sessions leaves out network.allowed_hosts, which can't be added to a browser created without one. stealth, headless, remote_forward, chrome_policy and kiosk_mode are also create-only. Consider adding them or rewording to "includes".
• remote_forward. ssh traffic doesn't count as browser activity, so the timeout needs raising. The user also needs the KERNEL CLI and websocat locally.
• search_docs. It dropped out of the routing table.

After merge: bump SKILLS_COMMIT in kernel-mcp-server to the merge commit on main.