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-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-5, gpt-6-sol). 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 a small set of built-in sub-agents: general-purpose (the catch-all), explorer (fast read-only reconnaissance — locates files and symbols without changing anything), and planner (read-only implementation planning) — 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 command that lists the working diff for review; it is not a sub-agent. See the Skills section below.)

Forked sub-agents: /subtask

The task tool (and the sub-agents above) start with a fresh context: the child sees only the prompt it was handed, which is why delegating means writing a brief. /subtask is the other shape — a sub-agent that starts from the conversation you are already having:

/subtask count the TODOs and tell me which ones are stale

What you get back is the difference that matters:

	task tool / /batch	/subtask
Starting context	fresh — only the prompt	a copy of this conversation
Where it runs	foreground (or background with run_in_background)	always background
Briefed as	a delegate that cannot see the chat	a fork that can read it
Report	returned as the tool result	arrives as a notification and continues the session

• It does not block you. The command returns immediately with Forked bg_…; you keep typing. /tasks lists it, /tasks stop <id> cancels it.
• The report comes back on its own. When the child finishes, its final message is wrapped in a <task-notification> and fed into the idle session as the next turn — the main agent reads it and carries on. The child's own words are not echoed into the transcript raw.
• It cannot ask you anything. A background agent has no way to prompt, so it may use only what the project's permission rules or the current mode already pre-approve (in plan mode that means reads only). A step it could not run is reported as needing you, instead of silently retried.
• It works in this same directory (or this session's worktree) — avoid editing the same files until it reports.
• It is bounded like any other sub-agent: same depth/session budget (maxSubagentsPerSession) and turn cap, and a fork that hits either says so in its report.

/fork is the unrelated one: it branches the session (a new copy of the conversation you continue yourself), not a background agent.

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 (e.g. claude-opus-5-5); omit to inherit.
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.
context	fork = run the skill as an isolated sub-agent instead of loading its text into this conversation. See below. Any other value warns and stays inline.
agent	With context: fork — which sub-agent type runs it (e.g. agent: explorer). Default general-purpose. Without a fork it warns and is ignored.
background	With context: fork — forked runs are backgrounded by default; false makes the invocation wait and return the report inline. Without a fork it warns and is ignored.

Forked skills (context: fork)

A fork skill's body never enters the invoking conversation. Instead the run is delegated to a sub-agent with a fresh context: the child gets the expanded skill body as its prompt and cannot see the conversation that invoked it, so a forked skill has to stand on its own. Only the report comes back.

---
name: deep-audit
description: Audit one subsystem against its spec and report drift.
context: fork
agent: explorer   # optional — which sub-agent type runs it
background: false # optional — default true
---
Audit $ARGUMENTS. ...

• Backgrounded by default — typing /deep-audit (or the model invoking it via use_skill) starts the run and returns immediately; the report arrives later as a task notification that continues the conversation. /tasks lists it while it runs.
• background: false waits: in the CLI the report prints when it lands; for the model the report becomes the tool result of the use_skill call.
• Headless runs always wait (nex --print, the SDK): there is no notification channel without an interactive session.
• The existing rules still apply to the child: deny: ["task(<agent>)"], the task depth limit, the session sub-agent budget, and model: on the skill (the child starts on that model).

Skills in subdirectories (nested discovery)

A monorepo package can keep its own playbooks: put them in <package>/.nexrall/skills/ and they are picked up lazily — not at startup, but as soon as the agent reads or edits a file in (or under) that package. The skill enters the catalogue on the agent's next request, so a packages/db migration playbook only costs context once the conversation actually goes there.

Nested skills are always addressed as <dir>:<name> — the project-relative directory, a colon, then the skill name (e.g. packages/cli:deploy). That scoped name is what the model sees in the catalogue and what you can type at the prompt. The scoping is what keeps them unambiguous: a nested skill can never silently shadow a top-level one, and foo always means the top-level skill.

Directories that are gitignored are skipped (node_modules, generated output) — naming one explicitly still works, but it never shows up on its own. Nested skills living in a package that also has .nexrall/commands/ are unaffected: nested discovery covers .nexrall/skills/ only.

Hot reload

Save a SKILL.md while a session is open and it is picked up within a few seconds — no restart, no /reload. A message tells you when the typed list actually changed (Skills reloaded: N available.); edits that don't change the list (a body tweak) stay quiet but still update what /name runs. This covers the project and global roots, including .agents/skills/. /reload remains the manual full re-read (skills, plugin assets and the project brief at once).

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 which older names still resolve.
• Plugins — bundle sub-agents, skills, commands, and hooks into one installable unit.
• Agent SDK — the same sub-agent/plugin format, loadable programmatically.