How to Validate Learned Site Skills Using the Validation Script in Ego-Lite

The Ego-Lite repository provides a TypeScript validation script at package/ego-browser/scripts/validate-site-skills.ts that checks your site skill manifests, tools, and notes against the required schema, exiting with code 0 on success or 1 on failure.

The citrolabs/ego-lite browser automation framework stores reusable "site skills" (notes, tools, and manifest data) under skills/ego-browser/learnings/. Before the runtime consumes these assets, you must validate learned site skills to ensure they conform to the expected schema and prevent runtime failures when agents request tools or notes.

Understanding the Validation Architecture

The validation pipeline consists of interconnected components that guarantee data integrity before the browser harness attempts to consume any learning assets.

Entry Point and CLI Wrapper

The primary interface is package/ego-browser/scripts/validate-site-skills.ts. This script resolves the validation root and orchestrates the validation process. It imports siteSkillsRoot() from src/learning/index.ts to determine the default directory containing all site-skill folders, and accepts an optional CLI argument to override this path with a custom location.

Core Validation Engine

The actual schema enforcement logic resides in package/ego-browser/src/learning/validate-learning-format.ts. This module exports validateSiteSkills(root), which walks every learning directory and delegates detailed checks to helper functions including validateLearning and validateLearnings. Because the runtime imports these same functions, validation guarantees that data will be consumable during actual browser automation execution.

How to Validate Learned Site Skills

You can run validation through the command line for development workflows or programmatically for CI/CD integration.

Validate Using Default Root

To check all skills in the canonical location determined by siteSkillsRoot():

cd package/ego-browser
node scripts/validate-site-skills.ts

Validate a Custom Directory

Pass a custom path as the first argument. The script warns if this path differs from the canonical root:

node scripts/validate-site-skills.ts ./my/custom/learnings

Programmatic Validation

Import the validation functions directly to embed checks into custom scripts or automation pipelines:

import { validateSiteSkills } from "./src/learning/index.js";

async function check() {
  const errors = await validateSiteSkills("./skills/ego-browser/learnings");
  if (errors.length) {
    console.error("Validation failed:", errors);
    process.exit(1);
  } else {
    console.log("All site skills are valid!");
  }
}
check();

Schema Validation Checks

When you validate learned site skills, the script performs comprehensive checks on every learning directory:

• Manifest integrity: Verifies required fields including id, name, and url are present in manifest.json
• Tool definitions: Validates nodeTools and browserTools objects for proper structure, checking description, args, returns, path, and callable properties
• Note files: Confirms that all notes are Markdown files located under the notes/ subdirectory
• Consistency: Ensures tool schemas match the expected format defined in the source code

Understanding Validation Results

The validation script provides clear exit codes for automation integrations:

• Exit code 0: Validation passed. The script prints site skills ok: <root> to stdout.
• Exit code 1: Validation failed. Detailed error messages are printed to stderr, specifying which files violated the schema.

Because the script uses the same validateSiteSkills, validateLearning, and validateLearnings functions as the runtime, successful validation guarantees that the browser harness can consume the data without runtime failures.

Summary

• The validation script at package/ego-browser/scripts/validate-site-skills.ts ensures site skills conform to the required schema before runtime consumption
• Use siteSkillsRoot() to locate the default learning directory or pass a custom path via CLI argument
• The validator checks manifest.json fields, tool schemas, and note file locations according to the logic in validate-learning-format.ts
• Exit codes 0 (success) and 1 (failure) enable seamless integration with CI/CD pipelines
• Programmatic access via validateSiteSkills() allows embedding validation into custom workflows and pre-commit hooks

Frequently Asked Questions

What files does the validation script check?

The script validates manifest.json files in each learning directory under the root path, plus associated note files in the notes/ subdirectory and tool definitions referenced by the manifest. It specifically checks for required fields like id, name, and url, and ensures tool definitions include description, args, returns, path, and callable properties.

Can I validate skills stored outside the default directory?

Yes. Pass the custom directory path as the first command-line argument to validate-site-skills.ts. The script will use this path instead of the default siteSkillsRoot() location, though it will warn you if the path differs from the canonical root defined in the source code.

What happens if validation fails?

The script prints detailed error messages to stderr describing which schema requirements were violated (such as missing required fields or invalid tool schemas), then exits with status code 1. This prevents the runtime from attempting to load malformed site skills that could cause agent execution failures during browser automation.

Is the validation logic shared with the runtime?

Yes. The script imports validateSiteSkills, validateLearning, and validateLearnings from src/learning/index.ts—the exact same modules used by the browser harness. This guarantees that data passing validation will be consumable by the runtime without additional format checks or transformation errors.

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