How the Ego-Lite Site Skills System Validates Learned Tools and Their Manifests

The ego-lite framework validates site skills through a rigorous three-stage pipeline that checks manifest integrity, tool schema compliance, and runtime file existence to ensure only safe, well-defined tools are loaded.

The validation system in the citrolabs/ego-lite repository ensures that every site skill—a reusable knowledge blob containing domain-specific notes and custom tools—meets strict structural and safety requirements before execution. Located in the learning package at src/learning/validate-learning-format.ts, the validateSiteSkills function orchestrates these checks to prevent runtime crashes and enforce consistent API contracts.

The Three-Stage Validation Pipeline

The validation process follows a strict sequence defined in validateLearning to guarantee that both static configuration and runtime code are trustworthy.

Stage 1: Manifest Integrity Checks

The validator first loads manifest.json and verifies fundamental structural requirements. According to the source code in validate-learning-format.ts (lines 20-48), the system checks that:

• The file contains valid JSON representing an object
• The id field matches the directory name containing the site skill
• The name field is a non-empty string
• The domains array contains at least one valid domain pattern
• Optional notes entries reference existing markdown files under the notes/ subdirectory

If any manifest field violates these constraints, the validator pushes a descriptive error to the results array before proceeding to tool validation.

Stage 2: Tool Schema Validation

Once the manifest passes integrity checks, the system validates the nodeTools and browserTools objects using validateToolMap (lines 106-115). This stage ensures that every declared tool follows a strict contract.

For each tool, validateToolSchema (lines 118-141) verifies:

• Safe naming: Tool keys must not contain slashes or ".." sequences
• Required metadata: Non-empty description and valid relative path fields
• Node-specific requirements: For Node tools, a non-empty callable name must be present
• Type definitions: The args and returns objects must follow the value-type schema validated by validateValueSchema (lines 160-174), ensuring properties are correctly typed as string, number, boolean, array, or object

Stage 3: Runtime Sanity Checks

The final stage performs physical file system verification and dynamic import testing. After static schema validation, validateLearning processes Node tools (lines 54-73) and browser tools (lines 75-82) separately.

For each tool file, the system:

1. Confirms file existence using requireFile (lines 221-225)
2. Rejects any temporary snapshot references using rejectTemporaryRefs (lines 227-236), which scans for @N or ref=N patterns that indicate incomplete code
3. For Node tools, dynamically imports the module (line 66) and verifies the exported callable is actually a function (lines 67-69)

If a tool file contains temporary references or fails to export the expected function, validation fails with a specific error message indicating the problematic file path.

Key Validation Functions in the Learning Package

The learning package exposes several critical functions that work together to enforce the validation pipeline:

• validateSiteSkills: The top-level entry point (lines 87-95) that iterates through all learning directories using iterLearningDirs and aggregates errors across all site skills
• validateLearnings: The underlying implementation that validateSiteSkills calls directly
• validateLearning: Processes individual site skill directories, coordinating manifest and tool validation
• validateToolMap: Walks the nodeTools and browserTools maps and delegates to schema validators
• validateValueSchema: Recursively validates type definitions for tool arguments and return values

These functions are exported from src/learning/index.ts and consumed by the CLI script at scripts/validate-site-skills.ts.

Running Validation in Your Workflow

You can integrate validation into your development workflow either programmatically or via the command line.

To validate all site skills programmatically:

import { validateSiteSkills } from 'ego-browser/src/learning';

// Validate all site-skills under the default learnings root
const errors = await validateSiteSkills();
if (errors.length) {
  console.error('Site-skill validation failed:');
  errors.forEach(e => console.error(' •', e));
  process.exit(1);
}

To load and inspect a single manifest manually:

import { loadLearningManifest } from 'ego-browser/src/learning';

// Load the manifest (throws if JSON is malformed)
const manifest = await loadLearningManifest('/path/to/site-skills/example');
console.log('Loaded manifest for', manifest.id);

To execute a validated Node tool from a site skill:

import { runNodeSiteTool } from 'ego-browser/src/learning';

const result = await runNodeSiteTool('exampleSite', 'login', { username: 'bob' });
console.log('Tool returned', result);

Summary

• Three-stage pipeline: The ego-lite validator checks manifest integrity, tool schema compliance, and runtime file existence in sequence
• Strict naming conventions: Tool names must be safe (no slashes or parent directory references) and match specific regex patterns
• Type safety: Arguments and return values must follow a strict value-type schema validated recursively by validateValueSchema
• Runtime verification: Node tools undergo dynamic import testing to ensure exported callables are valid functions
• Error aggregation: All validation errors are collected and returned as an array, allowing developers to fix multiple issues in one pass

Frequently Asked Questions

What happens if a site skill manifest has an ID that doesn't match its directory name?

The validator rejects the manifest with a descriptive error. In validate-learning-format.ts (lines 28-48), the system explicitly checks that the id field matches the directory name to ensure consistency between the filesystem structure and the declared skill identity.

Can browser tools and Node tools share the same validation logic?

While both use validateToolMap for schema validation (lines 106-115), Node tools undergo additional runtime checks. The system validates Node tools (lines 54-73) by dynamically importing the module and verifying the callable export, whereas browser tools (lines 75-82) only require file existence and absence of temporary references.

How does the system prevent temporary or snapshot code from being validated?

The rejectTemporaryRefs function (lines 227-236) scans each tool file for patterns like @N or ref=N that indicate temporary snapshot references. If found, validation fails immediately, ensuring only production-ready code passes the pipeline.

Where should I run the validation in my development process?

Run validateSiteSkills via the CLI script scripts/validate-site-skills.ts during continuous integration checks before deploying site skills. You can also call it programmatically in test suites to catch manifest or tool definition errors during development.

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