Skill Packs

How it works

A Skill Pack is a directory under ~/.blackbox/skills/<name>/ containing a manifest.json and a tools.js file. At engine startup, loadSkillPacks() (in apps/engine/src/skills/loader.ts) walks the skills directory, validates each manifest against a Zod schema, dynamically imports tools.js, and returns a LoadedSkillPack[].

Each pack declares its targetSpecialists — one or more of the 18 eligible specialists. When the matching specialist\'s delegate.ts starts a sub-agent, it calls attachSkillsToSpecialist(name, packs), which merges the pack\'s MCP servers into the specialist\'s mcpServers map and appends the pack\'s tool names to the allowed-tools list. The specialist sees the new tools as if they were built-in.

Loading is deliberately fail-soft. A bad manifest, a wrong-typed export, a missing env var — all produce a stderr warning, and that pack is skipped. A broken pack never takes down the engine. Equally deliberate: the zero-install default. A clean install has no ~/.blackbox/skills/ directory; loadSkillPacks() returns an empty array; every specialist behaves identically to a pre-Skill-Pack build.

The Skill Pack loader caps out at 18 eligible specialists exactly. The CEO and the Evaluator are not in the target list — the orchestration layer and the review layer stay skill-free so they\'re always the stable reference point.

What you see in the UI

The Skill Store view (apps/web/src/views/SkillStore.tsx) shows every installable skill with its name, value prop, required tier, required services, and an Install button. Installing a pack copies it into ~/.blackbox/skills/, restarts the engine, and the new capability is live.

You\'ll also see Skills referenced when the CEO proactively suggests an upgrade: "I\'ve drafted a landing page. Now you need leads to fill it. Want to install Lead Gen Bootstrap?" That\'s the CEO noticing that a Skill Pack would enable the next step.

A concrete example

The Lead Gen Bootstrap Skill Pack targets the Sales Specialist. Its tools.js exposes Apollo (prospect lookup) and SmartLead (sequence sending) as MCP tools. Its prompt addition teaches the Sales Specialist how to frame a cold email in your voice. Its playbook (playbooks/lead-gen-bootstrap.md) tells the CEO the exact sequence: define ICP → scrape → enrich → draft first messages → wait for owner approval → queue.

Install the Skill, paste your Apollo key, answer the ICP questions, go to bed. Overnight the Sales Specialist scrapes a few hundred prospects, filters them, drafts messages for the top 12, and queues 12 approval cards in your Inbox for morning.

Technical details

// apps/engine/src/skills/loader.ts
const manifestSchema = z.object({
  name: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
  version: z.string().min(1),
  description: z.string(),
  author: z.string(),
  engineCompatibility: z.string().optional(),
  targetSpecialists: z.array(z.enum(SKILL_PACK_TARGET_SPECIALISTS)).min(1),
  tools: z.array(z.object({
    name: z.string(),
    description: z.string(),
  })).optional(),
  // …prompt additions, playbook paths, env requirements…
});

Names starting with bb- are reserved (that prefix belongs to built-in servers like bb-ceo-tools). Every other lowercase kebab-case name is available.

Related features

• The 18 specialists — the targets Skill Packs can extend.
• Landing Page Bootstrap — the first built-in playbook, a reference for pack authors.
• Meta-learning loop — how Skills emerge from product usage.

Related concepts

• Specialist agent
• Agent delegation

FAQ