book-openSkills

Skills inject reusable domain knowledge into an agent's system context — either always-on or lazily loaded on demand.

circle-info

Since BoxLang AI v3.0+

Skills are named blocks of domain knowledge or instructions that can be injected into an agent's system context. Think of them as modular expertise — a SQL optimization skill, a security review skill, a brand voice skill — that you can mix and match across agents without duplicating instructions.

There are two modes:

  • Always-on skills (skills:) — content is injected into every system message

  • Lazy skills (availableSkills:) — an index is shown to the AI; full content is only loaded when the AI explicitly requests it via the built-in loadSkill() tool

Skill File Format

Skills are markdown files with optional YAML frontmatter, stored under .ai/skills/ by convention:

.ai/skills/
  sql-optimizer/
    SKILL.md
  coding/
    boxlang-expert/
      SKILL.md
  security/
    SKILL.md

Each SKILL.md file:

---
name: sql-optimizer
description: Expert SQL query optimization guidance. Use when writing or reviewing SQL queries.
---

## SQL Optimization Principles

Always use indexed columns in WHERE clauses...
Use EXPLAIN ANALYZE to profile slow queries...
Normalize data but denormalize for read-heavy tables...

If description is omitted, the first paragraph of the markdown body is used — matching the Agent Skills open standard.

Loading Skills

Always-On Skills

Full skill content is injected into the system context on every agent call:

Multiple always-on skills:

Lazy-Loaded Skills (availableSkills)

With lazy loading, only a compact index (name + description) is injected into the system context. The AI sees what's available and requests the full content of a skill when needed by calling the built-in loadSkill() tool:

Combining Both Modes

Use always-on for globally relevant skills and lazy-loading for specialized knowledge:

Global Skills

At the module level you can configure skills that are automatically available to every agent in your application:

Access the global pool at runtime:

Adding Skills After Construction

Last updated