Agents

Extras for @di-framework/ai. Agent Skills (SKILL.md, graduated disclosure) with filesystem, HITL questions, todos, optional web / memory / task, and opt-in Write/Edit/Bash.

This is a TypeScript counterpart of spring-ai-agent-utils. Skills run in your process. It is not Anthropic’s hosted Skills API.

Prefer builders: SkillsAgent.builder(), SkillsToolbox.builder(), SkillsTool.builder(). Free-function aliases remain. Skills stay in this package — configureAi/@Agent on AI are unchanged.

Features

Progressive disclosure: discovery embeds name + description; activation loads the full SKILL.md body and base directory.
Builder-first: SkillsAgent.builder() for a ChatAgent, SkillsToolbox.builder() to attach tools, SkillsTool.builder() for Skill only.
YAML front matter: maps, lists, scalars, |/> blocks; allowed-tools, license, compatibility, metadata.
Jailed file tools: Read, ListDirectory, Glob, Grep, opt-in Write/Edit/Bash.
Agent extras: TodoWrite, optional AskUserQuestion, web fetch/search, file memory, nested Task.
Enforcement: after a skill with allowed-tools activates, other tools are gated; file tools jail to workspace ∪ that skill.
Discovery: directories, single files, in-memory skills, npm packages, or neutral defaults at .agents/skills and ~/.agents/skills.
Plugins: discover and validate .agents/plugins bundles (plugin.json, nested skills, rules, mcp_config.json, hooks) without auto-wiring agents or MCP.
Project policy: hierarchical AGENTS.md instructions and root .aiignore enforcement with inspectable provenance and diagnostics.
Repository operations: read-only agent-configuration audits plus deterministic, dry-run-first neutral migration plans and explicit execution.

Installation

bun add @di-framework/ai-utils @di-framework/ai @di-framework/core

npm install @di-framework/ai-utils @di-framework/ai @di-framework/core

Peer: @di-framework/ai and @di-framework/core (required for decorator DX; builders work with both installed as shown above).

Quick start

import { OpenAiChatModel } from '@di-framework/ai';
import { SkillsAgent } from '@di-framework/ai-utils';

const agent = SkillsAgent.builder()
  .chatModel(new OpenAiChatModel({ model: 'gpt-4o-mini' }))
  .system('You help with TypeScript code review.')
  .workspace(process.cwd())
  .instructionDiscovery({ workingDirectory: 'src' })
  .aiIgnore('read-write')
  .write()
  .shell()
  .build();

await agent.chat('Review src/UserController.ts');

Attach the toolbox to an existing client:

import { ChatClient } from '@di-framework/ai';
import { SkillsToolbox } from '@di-framework/ai-utils';

const tools = SkillsToolbox.builder()
  .workspace(process.cwd())
  .buildTools();

const client = ChatClient.builder(model).defaultTools(...tools).build();

The ai-skills example has scripted tests (no API key) and a live bun start path that reviews fixtures/sample-user.ts with OpenAiChatModel (process.env.OPENAI_API_KEY).

The ai-plugins example validates the published @di-framework/plugin package, expands ${pluginDir} in mcp_config.json, and electively starts its stdio MCP (no API keys for local tools such as di_scaffold_provider).

Skill folders

A skill is a folder with a SKILL.md file (YAML front matter + instructions). Optional scripts/, references/, and other files stay on disk until the model reads them.

.agents/skills/
└── code-reviewer/
    ├── SKILL.md
    ├── references/
    │   └── checklist.md
    └── scripts/
        └── count-lines.sh

---
name: code-reviewer
description: Reviews TypeScript for nulls and framework conventions. Use when the user asks to review or audit code.
license: Apache-2.0
allowed-tools:
  - Read
  - Grep
metadata:
  author: you
---

# Code Reviewer

1. Read `references/checklist.md`
2. Check for null pointer risks
3. Suggest a concrete fix

name and description must satisfy agentskills.io rules. On disk, the folder name must match name. Invalid loaded skills fail closed.

Builders

Factory	Builds	When to use
`SkillsAgent.builder()`	`ChatAgent` + toolbox	Usual entry
`SkillsToolbox.builder()`	Toolbox (`build()`/`buildTools()`)	Existing `ChatClient`/`ChatAgent`
`SkillsTool.builder()`	`Skill` only	Tests, or when you already have file tools

.of(options) matches the older options-object APIs. Aliases: createSkillsAgent, createSkillsToolbox, skillsToolbox, skillsTool.

Shared toolbox methods

These exist on both SkillsAgent.builder() and SkillsToolbox.builder().

Method	Effect
`addSkillsDirectory`/`addSkillsDirectories`	Load `SKILL.md` trees
`addSkillsFile`	Load one `SKILL.md`
`addSkill`/`addSkills`	In-memory skills
`addPackage`/`addPackages`	npm package or path (`package.json` `skills`, else `.agents/skills`/`skills`)
`sourceMode('merge' \| 'replace')`	Supplement or replace the neutral automatic roots
`workspace`	Default cwd / search root (also an allowed file root)
`userDirectory`	Override the user root used for `~/.agents/skills`
`extraAllowedDirectory(s)`	Extra sandbox roots
`write()`/`shell()`	Opt-in `Write`+`Edit`/`Bash`
`aiIgnore('discovery' \| 'read' \| 'read-write')`	Enforce root `.aiignore` for direct file tools
`aiIgnorePolicy`/`onSuppressed`	Supply discovery policy and observe content-free suppressions
`confirmShell(fn)`	Approve or reject each `Bash` command
`askUser(handler)`	`AskUserQuestion`
`web(true \| { fetch, search, braveApiKey })`	`WebFetch`/`WebSearch`
`memories(true \| { directory })`	Long-term memory tools (`true` → `<workspace>/.memory`)
`task(true \| { chatModel, system })`	Nested `Task` (`true` uses `.chatModel()`)
`glob`/`grep`/`list`/`todos`	Pass `false` to omit (on by default)
`perSkillSandbox(false)`	Keep all skill dirs allowed after activate
`toolName`/`toolDescriptionTemplate`/`onActivate`	Customize the `Skill` tool

Agent-only methods

system, instructionDiscovery, chatModel, chatClient, extraTools, advisors, conversationMemory, defaultConversationId, defaultOptions, clientBuilderOptions.

build() returns ChatAgent. buildBundle() also returns the toolbox and inspectable repository instruction result.

Tools

Included by default	Opt-in
`Skill`, `Read`, `ListDirectory`, `Glob`, `Grep`, `TodoWrite`	`Write`/`Edit` (`.write()`), `Bash` (`.shell()`), `AskUserQuestion` (`.askUser()`), `WebFetch`/`WebSearch` (`.web()`), memory tools (`.memories()`), `Task` (`.task()`)

File tools are limited to workspace ∪ skill folders (and extras). After a skill with allowed-tools activates, other tools are denied by name.

Bash jails cwd only. It is not a container: the process can still use the network or cd elsewhere. Prefer a container for untrusted skills. Use confirmShell when a human should approve commands.

WebSearch needs BRAVE_API_KEY or .web({ braveApiKey }). Task subagents do not get AskUserQuestion or nested Task.

Discovery

The automatic roots are <workspace>/.agents/skills and ~/.agents/skills. In the default merge mode, explicit directories and packages precede the workspace and user defaults. Use sourceMode('replace') to use only explicit directories and packages. Duplicate skill names are deterministic: the first definition wins, and the toolbox exposes source and duplicate diagnostics.

addPackage('@scope/pack') resolves the package from the workspace, then uses package.json#skills or falls back to .agents/skills and skills under the package root. No vendor-specific path is loaded implicitly.

Repository instructions and ignore policy share the same boundary-safe source model. See Agent configuration for source provenance, catalog validation, AGENTS.md hierarchy, .aiignore discovery/direct modes, security precedence, typed repository audits, and plan-before-apply migration from vendor-specific layouts into neutral paths.

Large catalogs

Normal discovery places every skill name and description in the Skill tool. For catalogs above the default threshold of 50, generate a semantic index during the application build:

di-framework skills index build --skills-dir .agents/skills

Or call the same package implementation programmatically:

import { SkillsIndex } from '@di-framework/ai-utils';

await SkillsIndex.builder()
  .addSkillsDirectory('.agents/skills')
  .build();

This writes .di-framework/skills-index.json. Enable fail-closed retrieval with .semanticDiscovery() on SkillsAgent.builder() or SkillsToolbox.builder(). The default index is also detected automatically when present.

The default indexer uses the optional @huggingface/transformers peer. Install it only for large-catalog indexing (bun add @huggingface/[email protected]); small catalogs and custom embedders do not need it. Transformers.js tokenizes each exact SKILL.md into overlapping model-token chunks and embeds them locally with a pinned quantized BGE model. Runtime ranks skills using chunk cosine scores and sends only the top 10 names/descriptions to the chat model. Chunks and vectors do not enter the prompt; the full body remains lazy until activation. At or below the threshold, Transformers.js is not initialized and normal discovery remains active.

Very large catalogs can reuse the same SkillVectorSearch contract with SkillSearchRepository and SkillSearchIndexer over a SkillSearchConnection. SkillSearchConnection.fromVectorStore(new BunSqliteVectorStore({ ... })) stores float32 embeddings and builds a portable HNSW graph above the exact-scan limit; fromStorageAdapter accepts @di-framework/repo adapters. JSONL exact cosine stays the default discovery artifact.

Decorator DX

Thin decorators store catalog / retrieval / index metadata and apply helpers feed the same builders. Prefer builders for most apps; use decorators when you want DI-style declarations. Decorators never build indexes, load Transformers.js, or hide async work.

import { ScriptedChatModel } from '@di-framework/ai';
import {
  SemanticSkillDiscovery,
  Skill,
  Skills,
  SkillsIndexConfig,
  skillsAgentFrom,
  skillsIndexBuilderFrom,
} from '@di-framework/ai-utils';

@Skills({
  directories: ['.agents/skills'],
  packages: ['@company/skills'],
})
@SemanticSkillDiscovery({
  indexFile: '.di-framework/skills-index.json',
  limit: 10,
})
@Skill({
  name: 'code-reviewer',
  description: 'Reviews TypeScript code.',
  content: 'Check nulls and naming.',
})
class ApplicationSkills {}

const agent = skillsAgentFrom(ApplicationSkills, {
  chatModel: new ScriptedChatModel([]),
});

@SkillsIndexConfig({
  directories: ['.agents/skills'],
  threshold: 50,
  retrievalLimit: 10,
})
class ApplicationSkillsIndex {}

await skillsIndexBuilderFrom(ApplicationSkillsIndex).build();

Helpers: skillsToolboxOptionsFrom, skillsToolboxBuilderFrom/skillsToolboxFrom, skillsAgentBuilderFrom/skillsAgentFrom, skillsIndexBuilderFrom. Pass chatModel, custom SkillEmbedder, and stores as overrides — they are not stored on decorator metadata. Stack @Skills, @SemanticSkillDiscovery, and @Skill on one class; merge multiple catalog classes yourself. Terminal use goes through di-framework skills index; package APIs remain independent of command-line arguments and output.

Skill-only and MCP

import { agentSkill, SkillsTool, skillsToolboxAsMcp } from '@di-framework/ai-utils';

const skillOnly = SkillsTool.builder()
  .addSkill(
    agentSkill({
      name: 'xlsx',
      description: 'Build spreadsheets when asked for a spreadsheet.',
      content: 'Prefer a real .xlsx over a description.',
    }),
  )
  .build();

const mcp = skillsToolboxAsMcp({
  directories: ['.agents/skills'],
  workspace: process.cwd(),
});

skillsToolboxAsMcp returns descriptor + handler pairs from @di-framework/ai toolCallbackAsMcpTool.

Plugins

Plugins are filesystem bundles under .agents/plugins/<id>/ (and ~/.agents/plugins/<id>/):

.agents/plugins/<plugin-id>/
  plugin.json          # required; name optional (defaults to directory name)
  mcp_config.json      # optional { mcpServers: ... }
  hooks.json           # optional object
  skills/              # optional nested SKILL.md trees
  rules/               # optional *.md rule files

SkillsAgent/SkillsToolbox do not load plugins by themselves. Use the plugin APIs to discover and validate bundles, then wire pieces electively.

Automatic (discovery only)

Defaults are <workspace>/.agents/plugins then ~/.agents/plugins. Explicit directories/packages and sourceMode work like skill sources. A package that publishes plugin.json at its own root (for example @di-framework/plugin) resolves as a single-plugin source. Nested skills/ are validated with the skill catalog rules when you validate a plugin catalog.

import { resolvePluginSources, validatePluginCatalog } from '@di-framework/ai-utils';

const resolution = resolvePluginSources({ workspace: process.cwd() });
const catalog = validatePluginCatalog({ workspace: process.cwd() });
const fromPackage = validatePluginCatalog({
  packages: ['@di-framework/plugin'],
  sourceMode: 'replace',
});

Automatic here means where plugins are found, not that agents consume them.

Programmatic

import {
  loadPluginDirectory,
  loadPluginsDirectory,
  validatePluginDirectory,
} from '@di-framework/ai-utils';

const plugin = loadPluginDirectory('.agents/plugins/di-framework');
const fromRoot = loadPluginsDirectory('.agents/plugins');
const one = validatePluginDirectory('.agents/plugins/di-framework');

AgentPlugin exposes skillsDirectory, mcpConfig, rules, and hooks. This package does not start MCP servers or run hooks.

Elective (opt into an agent)

Validate the catalog, pass each plugin’s skills/ root into skill discovery, and append rule markdown to system context:

import {
  SkillsAgent,
  validatePluginCatalog,
} from '@di-framework/ai-utils';

const workspace = process.cwd();
const catalog = validatePluginCatalog({ workspace });
if (!catalog.valid) {
  throw new Error(catalog.diagnostics.map((d) => d.message).join('\n'));
}

const pluginSkillDirs = catalog.plugins
  .map((plugin) => plugin.skillsDirectory)
  .filter((path): path is string => path != null);

const ruleText = catalog.plugins
  .flatMap((plugin) => plugin.rules)
  .map((rule) => rule.content)
  .join('\n\n');

const agent = SkillsAgent.builder()
  .chatModel(model)
  .workspace(workspace)
  .addSkillsDirectories(pluginSkillDirs)
  .system(
    ruleText
      ? `You help with this codebase.\n\n${ruleText}`
      : 'You help with this codebase.',
  )
  .build();

MCP is elective the same way: read plugin.mcpConfig.mcpServers and register those entries with your MCP client (expand ${pluginDir} when present). Hooks stay data until you interpret hooks.json.

See the ai-plugins example for official @di-framework/plugin discovery plus elective MCP wiring.

SkillsAgent on kube — guest filesystem, model transport, and tool requirements before a complete agent deployment
AI — chat, tools, RAG, MCP, and agents (@di-framework/ai)
Agent configuration — neutral sources, validation, instructions, plugins, and .aiignore
Package README
Skills example
Plugins example

Last modified: 15 September 2026