How k-skill Uses CloakBrowser in Browser Mode: Runtime Detection and Execution

k-skill automatically detects CloakBrowser availability through environment variable inspection in the detectRuntime function, prioritizing the built-in browser tool when CLOAKBROWSER_PEEK_TOKEN or DOLSHOI_ACTION_BROKER_URL is present, while falling back to the portable k-skill-browser-runtime in generic environments.

The k-skill framework from NomaDamas/k-skill provides intelligent browser automation capabilities through its browser mode, which dynamically selects between the built-in CloakBrowser tool and portable runtime alternatives. This capability-based detection system ensures that skills running on Dolshoi-enabled agents leverage credential-aware browsing, while maintaining compatibility with standard environments. Understanding how k-skill detects and utilizes CloakBrowser requires examining the runtime detection logic and execution hierarchy implemented in the CLI source code.

Runtime Detection via detectRuntime

The core detection logic resides in packages/k-skill-cli/src/detect.js, where the detectRuntime function inspects process environment variables to determine browser capabilities.

function detectRuntime(env = process.env) {
  const dolshoi = Boolean(env.DOLSHOI_ACTION_BROKER_URL);
  const cloakBrowser = Boolean(env.CLOAKBROWSER_PEEK_TOKEN) || dolshoi;
  return {
    mode: dolshoi ? "dolshoi" : "generic",
    dolshoi,
    cloakBrowser,
  };
}

This function evaluates two critical environment signals:

• DOLSHOI_ACTION_BROKER_URL: Indicates the agent is running in Dolshoi mode with full credential access, which implicitly includes CloakBrowser capabilities.
• CLOAKBROWSER_PEEK_TOKEN: Explicitly signals that the built-in CloakBrowser tool is available for use.

The returned object contains a mode field (either "dolshoi" or "generic") and a boolean cloakBrowser flag that drives subsequent execution decisions throughout the CLI.

CloakBrowser Priority and Fallback Strategy

According to the design documentation in docs/dolshoi-runtime.md and docs/browser-runtime.md, k-skill implements a strict priority hierarchy for browser selection.

In Dolshoi runtime environments, CloakBrowser serves as the primary browser tool, with the generic portable runtime acting only as a contingency. The docs/browser-runtime.md file states: "Dolshoi uses the built-in CloakBrowser-backed tool as the primary browser; other environments fall back to k-skill-browser-runtime."

For generic runtime environments, the framework checks for CLOAKBROWSER_PEEK_TOKEN presence. When detected, CloakBrowser takes precedence; otherwise, the system deploys the portable k-skill-browser-runtime which interfaces with BrowserOS, Aside REPL, or Chrome CDP.

Instruction Assembly and User Feedback

When assembling skill instructions in packages/k-skill-cli/src/assemble.js, the CLI surfaces runtime information to users through the assemble function. The generated instructions include a diagnostic header:

Runtime mode: <mode> (CloakBrowser available)

This transparency allows developers to confirm which browser implementation will handle their skill's web automation tasks before execution begins.

Skill Execution Flow

During actual skill execution, the CLI follows a deterministic resolution path:

1. Detection: Invoke detectRuntime to assess the environment.
2. Capability Check: If runtime.cloakBrowser is true, initialize the agent's built-in browser capability.
3. Fallback: Otherwise, load the portable runtime (k-skill-browser-runtime) for browser session management.

This flow ensures CloakBrowser is always the first choice when available, delivering consistent, credential-aware browsing on Dolshoi-enabled agents while maintaining portability across standard environments.

Implementation Example: Detecting Runtime in Node.js

const { detectRuntime } = require("@nomadamas/k-skill-cli/src/detect");

// Simulate CloakBrowser availability
const env = { CLOAKBROWSER_PEEK_TOKEN: "token123" };
const runtime = detectRuntime(env);

console.log(runtime);
// → { mode: "generic", dolshoi: false, cloakBrowser: true }

CLI Assembly Example

# Assemble instructions for a skill

npx -y @nomadamas/k-skill@0 exec korean-cinema-search scripts/assemble.js

# Output includes:

# Runtime mode: generic (CloakBrowser available)

Summary

• k-skill detects CloakBrowser through environment variable inspection in packages/k-skill-cli/src/detect.js.
• The detectRuntime function checks for DOLSHOI_ACTION_BROKER_URL (Dolshoi mode) or CLOAKBROWSER_PEEK_TOKEN (explicit token).
• CloakBrowser receives priority over the portable runtime when available, ensuring credential-aware browsing on Dolshoi agents.
• The assemble function in packages/k-skill-cli/src/assemble.js exposes runtime status in generated instructions.
• Generic environments fall back to k-skill-browser-runtime when CloakBrowser tokens are absent.

Frequently Asked Questions

How does k-skill detect if CloakBrowser is available?

k-skill uses the detectRuntime function in packages/k-skill-cli/src/detect.js to check for the CLOAKBROWSER_PEEK_TOKEN environment variable. If this token is present, or if the agent is running in Dolshoi mode (indicated by DOLSHOI_ACTION_BROKER_URL), the framework sets cloakBrowser to true and prioritizes the built-in browser tool.

What is the difference between Dolshoi mode and generic mode in k-skill?

Dolshoi mode activates when the DOLSHOI_ACTION_BROKER_URL environment variable is present, indicating the skill runs on a credential-enabled agent that always includes CloakBrowser capabilities. Generic mode represents standard environments where CloakBrowser is only available if explicitly configured via CLOAKBROWSER_PEEK_TOKEN, otherwise falling back to the portable browser runtime.

Can I use k-skill browser mode without CloakBrowser?

Yes. When CLOAKBROWSER_PEEK_TOKEN is absent and the agent is not Dolshoi-enabled, k-skill automatically falls back to the k-skill-browser-runtime package. This portable runtime connects to alternative browser infrastructures like BrowserOS, Aside REPL, or Chrome CDP to execute web automation tasks.

Where can I verify which browser runtime my skill will use?

Check the assembled instruction output from packages/k-skill-cli/src/assemble.js. The generated instructions include the line Runtime mode: <mode> (CloakBrowser available) when the built-in browser is detected, or indicate the generic mode when using the fallback runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}