@atoms-agent/skills

Optional extension for atoms_agent: discover and lazily load local Claude/Codex-style SKILL.md directories, then expose them through Core tools.

This package depends only on @atoms-agent/core public contracts. It does not depend on @atoms-agent/mcp, does not execute skill scripts, and does not implement marketplaces, plugin loaders, or sandboxes.

Install

npm install @atoms-agent/[email protected] @atoms-agent/[email protected] @atoms-agent/[email protected]

Usage

import { createAgent } from "@atoms-agent/core";
import type { ModelAdapter } from "@atoms-agent/llm";
import {
  createSkillCatalog,
  createSkillTools,
  formatSkillCatalogPrompt,
} from "@atoms-agent/skills";

// Provide any ModelAdapter (OpenAI/Anthropic/ScriptedModel/etc).
declare const model: ModelAdapter;

const { catalog } = await createSkillCatalog({
  roots: ["/absolute/path/to/skills-root"],
});

const skillTools = createSkillTools({ catalog });
const skillPrompt = formatSkillCatalogPrompt({ catalog });

const agent = createAgent({
  model,
  systemPrompt: `Use local skills when helpful.\n${skillPrompt}`,
  tools: skillTools,
  authorize: () => "allow",
});

Host must pass explicit skill roots. list_skills / load_skill / read_skill_resource are read-only and never execute scripts/.

For offline demos, install @atoms-agent/testing as a dev dependency and pass createScriptedModel(...) as model.

Only import from the package root. Subpath / deep imports are not supported.

Requirements

• Node.js >= 22.13
• ESM

License

MIT