@nightowlsdev/agent-kit

Pre-built agents

The shared foundation for the pre-built agent family: curated skills.sh manifests + governed batch import, fail-loud tool contracts, progressive-disclosure skill-library tools, and persisted-store lifecycle helpers.

What it does

@nightowlsdev/agent-kit is what the pre-built agent packages (builder/researcher/marketer/designer/writer) are made of, and what you use to build your own. A `CuratedSkillSet` manifest pins external skills.sh refs to reviewed snapshot hashes; `importCuratedSkills` batch-imports them through the governed skills seam (default `pinMode: 'strict'`: a drifted upstream is skipped for review, a renamed upstream is rejected in every mode, failures are isolated per ref) and `verifyGrants` makes the silent-miss mode legible (a granted stored name with nothing behind it injects nothing). `skillLibraryTools` solves the 18-skills-without-prompt-explosion problem: an agent holds a big curated library at ~zero prompt cost and reads one skill on demand as a FENCED tool result, scoped to an explicit name list (never whole-tenant). `assertToolRequirements` makes capability contracts fail loud at factory time. `ensurePrebuiltAgent` (boot-safe seed-if-absent) and `publishPrebuiltAgent` (the deliberate upgrade) speak core repo contracts only, the 'evolve once, upgrade downstream' lifecycle on a persisted store.

Install

pnpm add @nightowlsdev/agent-kit

Key exports

importCuratedSkills / verifyGrants (strict pins, rename rejection, per-ref isolation)
skillLibraryTools (skill_library_list / skill_library_read, fenced, scoped)
assertToolRequirements (fail-loud capability contracts)
ensurePrebuiltAgent / publishPrebuiltAgent (persisted-store lifecycle)
buildAgentSpec / PrebuiltAgentManifest / PrebuiltAgentOpts
ALL_PREBUILT_TOOL_NAMES / PREBUILT_READONLY_TOOL_NAMES

Usage

agent-kit.ts

import { importCuratedSkills, verifyGrants, ensurePrebuiltAgent } from "@nightowlsdev/agent-kit";
import { skillsShProvider } from "@nightowlsdev/skills";
import { createResearcher, manifest } from "@nightowlsdev/agent-researcher";

// 1. Import an agent package's curated manifest (strict pins: drift is skipped, renames rejected).
await importCuratedSkills({
  sets: manifest.curatedSkills,
  providers: { "skills.sh": skillsShProvider() },
  storage,                                   // { skills, skillsWritable }, createSupabaseStorage has both
  tenantId,
  actor: { type: "service", serviceId: "seed", tenantId },
});

// 2. Verify the grants resolve (a granted stored name with nothing behind it injects nothing).
const { missing } = await verifyGrants(storage.skills, tenantId, ["deep-research", "research-synthesis"]);

// 3. Seed the factory's agent on a persisted store (publishPrebuiltAgent is the deliberate upgrade).
const researcher = createResearcher({ tools: { webSearch: myWebSearchTool } });
await ensurePrebuiltAgent({
  agents: storage.agents, agentsWritable: storage.agentsWritable,
  def: researcher, tenantId, actor: { type: "service", serviceId: "boot", tenantId },
});

// The full journey (tier config, dynamicSkills, approvals): /docs/adopt-prebuilt-agents