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

> Discover how ego-lite site skills validates learned tools and manifests using a three-stage pipeline. Ensure safe, well-defined tools are loaded for your projects.

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

---

**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](https://github.com/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/manifest.json) and verifies fundamental structural requirements. According to the source code in [`validate-learning-format.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) and consumed by the CLI script at [`scripts/validate-site-skills.ts`](https://github.com/citrolabs/ego-lite/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.