Custom Skills, Agents & Rules in nexus

nexus skill add / nexus agent add / a new rule in knowledge/rules — build the asset once, every session benefits.

RULE + AGENT + SKILL

Module Overview

This is the Dev Track's equivalent of Module 6. The core program teaches rules, agents, and skills as three layers of portable markdown you build by hand. nexus ships five working examples of exactly that pattern — the reviewer skills and subagents from Dev 5 — plus CLI commands that scaffold new ones for you. Study the built-ins first; they're the reference quality bar for what you build next.

At a glance
Covers	`nexus rule add`, `nexus skill add`, `nexus agent add`; reading the built-in reviewer agents as design references; tool-scope governance; `nexus sync` vs. custom assets
When it runs	Once a correction (Dev 3) or a recurring task (Dev 5) shows up more than twice
Builds on	Dev 3 (the rule candidates) and Dev 5 (the built-in reviewers)
Leads into	Dev 7 — committing and sharing what you built

What you'll produce

One rule added to AGENTS.md or knowledge/rules/, one custom skill, and one custom agent — each tested against a real task and committed to the project's knowledge/ directory.

The Three Commands

nexus rule add api-standards      # creates a project rule under knowledge/rules/
nexus skill add my-review         # creates a custom skill in .claude/commands/
nexus agent add my-agent          # creates a custom subagent in .claude/agents/

nexus skill list                  # list all skills in .claude/commands/
nexus agent list                  # list all subagents in .claude/agents/
nexus rule list                   # list all rules in knowledge/rules/

OpenCode note

These commands write to .claude/commands/ and .claude/agents/ regardless of which tool your project was initialized for — if you ran nexus init . --tool opencode, copy the new skill or agent file into .opencode/commands/ or .opencode/agents/ yourself afterward (same as nexus's own docs describe for custom skills). If it's an agent with tools or model frontmatter, drop those two fields when you copy it — OpenCode configures both differently, and nexus init strips them from the built-in agents for the same reason.

Asset	When to reach for it	Same idea in the core program
Rule	A standard applies to every EPAV run — error format, a cross-file dependency to always check	Module 6, Part 1 — "always-on guidance"
Agent	A recurring, scoped task you invoke by name for a second opinion (a new reviewer type, a domain check)	Module 6, Part 2 — "a prompt promoted to a saved role"
Skill	Domain expertise that should load only for matching tasks, not bloat every EPAV run	Module 6, Part 3 — "packaged expertise, loaded on demand"

Study the Built-Ins First

Before writing your own, read .claude/agents/code-reviewer.md. It's a real, working example of every design principle Module 6 teaches:

---
name: code-reviewer
description: MUST BE USED for code reviews, code quality analysis,
  best practices enforcement, design patterns, refactoring suggestions,
  and maintainability improvements. Use proactively after code changes.
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
---
You are an expert Code Reviewer. Before reviewing any code, you MUST
first discover the context of the repo you are working in.
...

What to notice	Why it matters
"MUST BE USED" + "Use proactively" in the description	Drives auto-delegation — the more precise the description, the more reliably the right agent gets picked
"Required Output Format" specified exactly, including a JSON schema	Nothing is left to the model's formatting discretion — downstream tooling can parse it
"Only after completing the above should you begin the review"	Forces context discovery before judgment — the agent equivalent of EVALUATE before PLAN

Build Your Rule, Agent, or Skill — E→P→A→V

Same cycle, aimed at the asset itself instead of a feature.

[EVALUATE]

What have I corrected the AI on more than once this sprint (Dev 3's rule candidates)? Is it always-on (rule), a recurring named task (agent), or occasional domain expertise (skill)? Read the closest existing example in knowledge/ or .claude/agents/ first.

[PLAN]

Name (kebab-case), one-sentence description precise enough to drive delegation, the minimum tool scope it needs, an explicit "never do" list, and the exact output format. Review this before running the add command.

[APPLY]

nexus rule add <name> / nexus skill add <name> / nexus agent add <name>, then write the file to match the plan exactly.

[VALIDATE]

Start a fresh session. Run a real task that should trigger it. Does it fire without being told explicitly? Does the output match the specified format? If not on the first or second try, the scope or description is unclear — revise, don't just re-run.

Governance: Tool Scope

code-reviewer is granted Read, Write, Edit, Bash, Grep, Glob but its system prompt constrains it to reporting, not editing — a reminder that tool access and behavioral constraint are two separate governance levers. When in doubt, grant fewer tools; expanding scope later is easy, contracting it after an incident is not.

Agent type	Tools to grant	Tools to withhold
Reviewers and checkers	Read, Grep, Glob	Write, Bash (cannot modify files)
Implementers (like /apply itself)	Read, Write, Bash	Scope Bash to specific directories in the system prompt

nexus sync vs. Your Custom Assets

nexus sync updates the built-in skills and agents (the EPAV cycle, the five reviewers) to the latest version shipped with the toolkit — and leaves anything you added under a different name untouched. nexus update --sync does the same after updating the CLI itself. This is why custom assets should always get a distinct name from the built-ins: a sync should never silently overwrite work you committed.

Self-Check

I've read .claude/agents/code-reviewer.md and can point to its description, tool scope, and output format sections.
I can decide whether a recurring correction needs a rule, an agent, or a skill.
I've built and tested one custom asset with nexus rule/skill/agent add.
I understand why tool scope and behavioral constraints are separate governance levers.
I know that nexus sync won't touch my custom assets as long as they're named differently from the built-ins.