Sub-agents & skills
Two ways to give the agent reusable, specialized capabilities: sub-agents (narrow personas with a scoped tool set) and skills (reusable playbooks loaded on demand).
Sub-agents
A sub-agent is a specialist the main agent delegates to for a focused piece of work. Each sub-agent runs in its own context, with its own tool allowlist and (optionally) its own model — so a code-reviewer sub-agent can be read-only, while a test-writer sub-agent can only touch test files.
Defining a sub-agent
Write a Markdown file in .nexrall/agents/ (project) or ~/.nexrall/agents/ (everywhere). The frontmatter is the sub-agent's definition:
---
name: code-reviewer
description: Reviews diffs for bugs, edge cases, and security issues. Use before merging.
tools: read_file, search_files, glob
model: claude-opus-5
---
You are a code reviewer. You never modify files — you only report findings…| Field | Meaning |
|---|---|
name | The sub-agent's name, used to invoke it. |
description | When to delegate to it — this is what decides when the main agent picks it. |
tools | Allowlist of tools this sub-agent may use (omit to grant all). |
model | Optional model override — a real model id (e.g. claude-opus-5, gpt-5.4) is preferred; the legacy turbo / pro / ultra / fast tier aliases still resolve too, see Models. Omit to inherit the session's. |
memory | Optional — gives this sub-agent its own private notes across runs. |
The body below the frontmatter is the sub-agent's system prompt: give it a method, hard rules, and the output shape you expect.
Nexrall ships built-in sub-agents (reviewer, security-auditor, explorer, planner, test-writer, devops-advisor, and a general-purpose catch-all) — your .nexrall/agents/ files extend and override them by name. Resolution order is project → global (user) → plugin → built-in (see Plugins).
(/review is a separate thing — a built-in skill, invoked with a leading slash. See the Skills section below.)
Skills
A skill is a reusable playbook the agent loads on demand — a Markdown file with instructions for a specific task, often with supporting files.
Skills use Agent Skills — the open SKILL.md format Anthropic published in December 2025, now adopted by 26+ AI coding tools (Claude Code, Codex, Gemini CLI, Cursor, and more). A skill you write for Nexrall works unmodified in any of those tools, and vice versa — nothing here is a Nexrall-only format.
Skills live in .nexrall/skills/<name>/SKILL.md (project) or ~/.nexrall/skills/ (global), and are loaded via the use_skill tool or picked from the composer's / menu. A skill's description is what decides when the agent (or you) should reach for it — only the name + description of every installed skill sit in context up front; the full body loads only when the skill is actually used ("progressive disclosure").
---
name: refactor
description: Safely refactor code — plan, verify call sites, apply stepwise with tests.
---
# Refactor
…the reusable instructions…| Field | Meaning |
|---|---|
name | The skill's name, used to invoke it as /name. Should be lowercase letters, numbers, and hyphens, matching its directory name — Nexrall loads it anyway if not, but warns, since other clients reading the same file may be stricter. |
description | When to reach for it — what the model reads to decide whether to auto-invoke via use_skill. |
model / mode | Optional overrides, same meaning as a sub-agent's — a real model id is preferred; see Models for the legacy tier aliases. |
disable-model-invocation | true = only /name can invoke it (for side-effecting workflows like a /deploy skill). |
user-invocable | false = only the model may invoke it — background knowledge, not a typeable command. |
license | Spec field — the license covering this skill. Informational. |
compatibility | Spec field — environment requirements (e.g. "Requires git, docker"). Informational. |
allowed-tools | Spec field (experimental) — tools the skill expects to use. Informational; not yet enforced as an allowlist. |
metadata | Spec field — a nested map of arbitrary author metadata (e.g. author, version). Never merged into the fields above, even if a key name collides. |
Cross-client skills: .agents/skills/
Alongside .nexrall/skills/, Nexrall also scans .agents/skills/ (project and user scope) — the convention the Agent Skills spec calls out for sharing skills between different clients. A skill placed there by, or for, another compliant tool is picked up automatically; no re-authoring needed.
.agents/skills/ is deliberately the lowest-priority source: if a skill of the same name also exists under .nexrall/skills/ or as a .nexrall/commands/*.md, that one wins. A skill you configured explicitly for Nexrall should never be silently shadowed by one meant for a different tool.
Because a skill is a playbook the agent will follow, both directories are called out in the workspace-trust prompt the first time you open a project — same treatment as .nexrall/skills/.
Next steps
- Configuration — where
.nexrall/agents/and.nexrall/skills/live. - Models — the full model catalogue and the legacy tier aliases
model:also accepts. - Plugins — bundle sub-agents, skills, commands, and hooks into one installable unit.
- Agent SDK — the same sub-agent/plugin format, loadable programmatically.