Federico Del Gaudio
Norn docs Agent skills Contents
Back to project
•
3 min read

Agent skills

Table of Contents

Norn includes a shared norn-review skill for Codex and Claude Code. It turns the headless CLI into a repeatable agent workflow: after the normal repository checks pass, the coding agent runs an independent Norn review before completing the task and before pushing code.

The skill reviews changes but never commits, pushes, publishes provider comments, or broadens permissions on its own.

Requirements

Install Norn and authenticate at least one supported AI provider first:

norn --version
claude --version  # when using Claude
codex --version   # when using Codex
norn doctor --machine-only

The skill source is distributed in the Norn repository at integrations/agent-skills/norn-review.

Install for Codex

Clone Norn, then link the shared skill into the Codex personal skills folder:

git clone https://github.com/delaudio/norn.git
mkdir -p "$HOME/.codex/skills"
ln -s "$(pwd)/norn/integrations/agent-skills/norn-review" \
  "$HOME/.codex/skills/norn-review"

Restart Codex if the skill is not discovered in the current session. Invoke it explicitly with:

$norn-review

Codex can also select it automatically after implementation work or when a task is about to push code, based on the skill description.

Install for Claude Code

Link the same skill into Claude Code’s personal skills folder:

mkdir -p "$HOME/.claude/skills"
ln -s "$(pwd)/norn/integrations/agent-skills/norn-review" \
  "$HOME/.claude/skills/norn-review"

Invoke it explicitly in Claude Code with:

/norn-review

Claude Code can also load it automatically when the request matches its description. Personal skills are available across local projects.

What the skill runs

For uncommitted implementation changes, the default gate is equivalent to:

norn review \
  --repo-path . \
  --scope working-tree \
  --format json \
  --fail-on-findings

For already committed changes, it uses branch scope. When committed and uncommitted changes coexist, it reviews both scopes separately and deduplicates findings.

The configured default AI provider is used unless the task explicitly selects one. To force a provider for a review:

norn review --repo-path . --scope working-tree \
  --format json --fail-on-findings --ai-provider codex

Replace codex with claude to use Claude.

Findings and exit codes

  • Exit code 0 means the review completed without a configured failing condition.
  • Exit code 1 means the review found issues at or above the configured threshold.
  • Exit code 2 or greater means setup, configuration, provider, analyzer, or runtime failure. It is not a code finding.

The agent fixes only high-confidence findings that belong to the current change, reruns the affected checks, and performs one bounded Norn rerun. A provider or runtime failure stops the gate instead of being silently treated as a successful review.

The post-task workflow skips optional repository analyzers because the coding agent has already run the project’s normal validation commands. Use --run-analyzers only for an explicit standalone review that should execute the configured non-mutating analyzers.