Documentation•Reference

HazelJS Skillgate Package

npm downloads

@hazeljs/skillgate turns selected REST / OpenAPI endpoints into curated, governed agent skills — then registers them on @hazeljs/agent ToolRegistry (and optionally @hazeljs/mcp).

Quick Reference

  • Purpose: Gate which APIs become LLM tools (allowlist, classify, HITL on writes).
  • When to use: Brownfield Hazel APIs that need an agent surface without dumping every CRUD route.
  • Key APIs: Skillgate.fromOpenApi, Skillgate.fromModule, list, report, register, toMcpServer, @AgentSkill, defaultSkillgateOptions.
  • Dependencies: @hazeljs/agent (required); @hazeljs/swagger / @hazeljs/mcp / @hazeljs/core optional peers.
  • Common mistakes: include.mode: 'all' in prod; skipping write approvals; tool explosion (>12 skills).

Installation

npm install @hazeljs/skillgate @hazeljs/agent

Minimal example

import { Skillgate, defaultSkillgateOptions } from '@hazeljs/skillgate';
import { ToolRegistry } from '@hazeljs/agent';

const gate = Skillgate.fromOpenApi(
  openApiSpec,
  defaultSkillgateOptions({
    include: { tags: ['agent'] },
    invoke: { baseUrl: 'http://127.0.0.1:3000' },
  })
);

const registry = new ToolRegistry();
gate.register(registry, 'api-concierge');
console.log(gate.report());

fromModule

import { Skillgate } from '@hazeljs/skillgate';

const gate = Skillgate.fromModule(AppModule, {
  swagger: { title: 'My API', servers: [{ url: 'http://127.0.0.1:3000' }] },
  invoke: { baseUrl: 'http://127.0.0.1:3000' },
});

Requires @hazeljs/swagger. Controllers tagged agent / skillgate, or methods with @AgentSkill, are opted in.

MCP export

const server = gate.toMcpServer({ name: 'hazel-api-skills', version: '1.0.0' });
server.listenStdio();

Requires @hazeljs/mcp.

CLI

hazel skillgate from-openapi ./openapi.json
hazel skillgate init
hazel add skillgate

Guide

Full walkthrough (include modes, safety table, Agent OS wiring, troubleshooting): Skillgate guide.

License

Apache-2.0