# How to Use the `site` Facade for Site Skills in ego-lite

> Master the ego-lite `site` facade to discover and run site skills like runTool and lookup. Execute agent scripts efficiently without manual imports and enhance your application's capabilities.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-27

---

**The `site` facade in ego-lite provides a runtime interface for discovering and executing site-specific skills through methods like `runTool()`, `runBrowserTool()`, and `lookup()`, automatically injected into agent scripts without requiring manual imports.**

The ego-lite framework exposes a powerful abstraction layer for browser automation through the `site` facade, enabling agent scripts to interact with domain-specific capabilities called **site skills**. This facade is automatically injected into the helper context via `helperContext()` in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), allowing seamless access to Node tools and browser tools defined in site-specific manifests. Understanding how to leverage the `site` facade unlocks the full potential of ego-lite's modular skill system for complex web automation tasks.

## Understanding the Site Facade Architecture

The `site` facade operates as a runtime bridge between agent scripts and site-specific skill definitions stored in `skills/ego-browser/learnings/<site-id>/manifest.json`. According to the ego-lite source code in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts), the facade exposes four primary methods for skill interaction: `runTool()` for Node environment execution, `runBrowserTool()` for browser context evaluation, `lookup()` for domain resolution, and `knowledge()` for retrieving site metadata.

Under the hood, domain matching occurs in [`src/learning/check-domain-learning.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/check-domain-learning.ts), which iterates over all learning directories to match hostnames against manifest domain arrays. Once matched, [`src/learning/validate-learning-format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/validate-learning-format.ts) validates the manifest structure before tool execution proceeds.

### Core Facade Methods

The facade provides these essential entry points:

- **`site.runTool(siteId, toolName, args)`** – Executes a Node tool defined in the site's manifest within the agent's Node environment.
- **`site.runBrowserTool(siteId, toolName, args)`** – Executes a browser tool via Chrome DevTools Protocol (CDP) inside the controlled browser context.
- **`site.lookup(urlOrHostname)`** – Resolves a URL or hostname to its matching site skill, returning `{ siteId, siteName }` or `null`.
- **`site.knowledge(url)`** – Retrieves compiled site metadata including notes and selector hints for LLM prompting.

## Site Skill Structure and Manifest Files

Before invoking facade methods, ego-lite expects site skills to follow a specific directory structure. Each site skill resides in its own subdirectory under `skills/ego-browser/learnings/` and must contain a [`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) file defining the site's capabilities.

A valid manifest includes:

- **`domains`**: Array of hostnames the skill targets.
- **`nodeTools`**: Definitions for Node.js environment tools.
- **`browserTools`**: Definitions for browser-context tools.
- **`notes`**: Documentation content for LLM prompting.

## Executing Node Tools with site.runTool

The `site.runTool(siteId, toolName, args)` method executes Node-based tools defined in a site's manifest. This method, implemented in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts), dynamically imports tool files using `loadNodeTool` and validates the exported callable before invocation.

```javascript
// Resolve site and execute Node tool
const url = "https://example.com/product/123";
const info = await site.lookup(url);

if (info) {
  const price = await site.runTool(info.siteId, "priceLookup", { 
    productId: "123" 
  });
  console.log("Price:", price);
}

```

The method signature accepts three parameters: `siteId` (the directory name), `toolName` (the key from `nodeTools`), and `args` (an object passed to the tool function).

## Running Browser Tools with site.runBrowserTool

For operations requiring direct browser interaction, `site.runBrowserTool(siteId, toolName, args)` injects tool source into the controlled browser context. This method utilizes the helper `js()` function to evaluate scripts within the page environment via CDP, returning DOM-extracted data directly to the agent script.

```javascript
// Extract page title using browser-side tool
await site.runBrowserTool("hackernews", "extractTitle", { 
  selector: "h1.title" 
})
.then(title => console.log("Page title:", title));

```

## Resolving Sites with site.lookup

Before executing tools, scripts typically resolve URLs to site skills using `site.lookup(urlOrHostname)`. This method parses the input URL and compares it against the `domains` array in each manifest file, as implemented in [`src/learning/check-domain-learning.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/check-domain-learning.ts).

```javascript
const info = await site.lookup("https://news.ycombinator.com");
if (info) {
  console.log(`Matched site: ${info.siteName} (${info.siteId})`);
}

```

## Retrieving Site Knowledge

The `site.knowledge(url)` method retrieves compiled site metadata including notes content and selector hints. This information proves valuable for constructing LLM prompts with domain-specific context.

```javascript
const knowledge = await site.knowledge("https://news.ycombinator.com");
console.log("Site notes:", knowledge.notes);
console.log("Selector hints:", knowledge.selectorHints);

```

## Complete Integration Example

The following example demonstrates combining lookup, browser tools, and Node tools within a task-space script where the `site` object is pre-injected:

```javascript
// Check if site exists for the URL
if (await site.lookup("https://news.ycombinator.com")) {
  // Extract data using browser tool
  const items = await site.runBrowserTool(
    "hackernews", 
    "listTopPosts", 
    { limit: 5 }
  );
  
  // Process with Node tool
  const summary = await site.runTool("hackernews", "summarizePosts", {
    posts: items
  });
  
  console.log(summary);
}

```

## Summary

- The **`site` facade** is automatically available in ego-lite agent scripts through [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), requiring no manual imports.
- Site skills are stored in **`skills/ego-browser/learnings/<site-id>/`** with a mandatory **[`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json)** file.
- Use **`site.lookup()`** to resolve URLs to site IDs before invoking tools.
- **`site.runTool()`** executes Node.js environment tools, while **`site.runBrowserTool()`** runs code inside the browser context via CDP.
- The domain matching logic lives in **[`src/learning/check-domain-learning.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/check-domain-learning.ts)**, and tool dispatch is handled in **[`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts)**.

## Frequently Asked Questions

### What is the site facade in ego-lite?

The `site` facade is a runtime interface exposed through the helper context that enables agent scripts to discover and invoke site-specific skills. It abstracts the complexity of loading manifests, matching domains, and dispatching tools, allowing developers to interact with website-specific automation logic through a consistent API.

### How does site.runTool differ from site.runBrowserTool?

**`site.runTool()`** executes Node.js modules within the agent's Node environment, suitable for API calls, data processing, or file system operations. **`site.runBrowserTool()`** injects and executes JavaScript inside the controlled browser page via Chrome DevTools Protocol, enabling DOM manipulation, element extraction, and page interaction that requires actual browser context.

### Where are site skill manifests stored?

Site skill manifests are located at `skills/ego-browser/learnings/<site-id>/manifest.json` relative to the ego-lite installation. Each site ID corresponds to a subdirectory containing the [`manifest.json`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) file that declares domains, tools, and metadata for that specific site.

### Do I need to import the site facade manually?

No. The `site` facade is automatically injected into the helper context by `helperContext()` in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts). When running scripts through the `ego-browser` CLI or within a task-space, the `site` object is available as a global-like variable without requiring import statements or explicit initialization.