Skills

A skill is a SKILL.md package — frontmatter plus instructions — that teaches the model how you want a task done. Skills guide reasoning; the sandbox-backed tools perform execution. Nexo does not implement skill loading; it composes the ruby_llm-skills gem so you attach a skill with one macro and no loader setup.

A skill package

Drop a package under app/skills/ (or scaffold one — see below):

app/skills/
└── triage/
    ├── SKILL.md          # frontmatter (name, description) + process steps
    └── references/       # supporting docs the skill can cite

---
name: triage
description: Triage incoming issues by severity and route them to the right owner.
---

# Triage

## Process
1. Classify the issue severity.
2. Route to the right owner.

Reference it with the skills macro — its instructions are layered on top of the agent’s own, in declaration order:

require "nexo"

class TriageAgent < Nexo::Agent
  model ENV.fetch("NEXO_MODEL")   # any ruby_llm model — never a hardcoded vendor default
  skills :triage                  # one macro, no loader wiring
end

TriageAgent.new.chat   # chat built with the base sandbox tools + the skill's instructions

Scaffold a skill

Scaffold a new skill package with the generator (creates a valid SKILL.md plus a references/ directory):

rails g nexo:skill triage
#   create  app/skills/triage/references/.keep
#   create  app/skills/triage/SKILL.md

An optional dependency

ruby_llm-skills is an optional dependency — required lazily only when you use a skill. Without it installed, require "nexo" still loads; touching a skill raises a clear Nexo::MissingDependencyError telling you to add gem "ruby_llm-skills". Referencing a skill that does not exist raises Nexo::Error naming the missing SKILL.md path.

Skill tools stay gated

A skill contributes instructions only. A loaded skill ships no independent tools, and Nexo deliberately does not attach ruby_llm-skills’ progressive-disclosure tool (which reads files outside the sandbox). The model reaches a skill’s references//scripts/ files through Nexo’s own permission-gated, sandbox-backed tools — so attaching a skill never widens what an agent can do beyond its configured sandbox/permission mode.

Safe by default: skills add reasoning, never authority. A :read_only agent with a skill is still :read_only.

Live example

A runnable example points a code-reviewer agent at a local Ollama model, attaches a ruby-code-review skill, and accounts tokens per prompt:

NEXO_MODEL=gemma3:12b ruby -Ilib examples/code_reviewer.rb

The skill package it uses lives at examples/skills/ruby-code-review/SKILL.md in the repo.

View examples/code_reviewer.rb on GitHub →

Next steps