Agent skills

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 Homebrew formula includes the version-matched skill source. Installation does not require cloning the Norn repository or maintaining symlinks.

Install

Install the skill for Codex, Claude Code, or both:

norn skills install --agent codex
norn skills install --agent claude
norn skills install --agent all

Installation is idempotent. Running it again upgrades Norn-managed copies to the skill bundled with the active norn executable. Existing unmanaged skill directories are preserved unless you explicitly approve replacement:

norn skills install --agent all --force

Use --force only after reviewing the reported conflict.

After brew upgrade norn, Homebrew has updated the packaged skill source but not the copies in your personal agent directories. Refresh them explicitly:

norn skills install --agent all
norn skills status --agent all

Run norn skills --help for the complete command and flag reference.

Source builds

Debug builds run from a Norn source checkout discover the repository’s bundled skill automatically. For a custom release layout, point Norn at the directory that contains norn-review:

NORN_AGENT_SKILLS_DIR=/path/to/norn/integrations/agent-skills \
  norn skills install --agent all

This copies a managed skill into each selected agent directory; a manual symlink is not required.

Inspect and remove

Status output reports each agent, managed state, and installed version without exposing personal filesystem paths:

norn skills status --agent all
norn skills status --agent all --json

Uninstall removes only Norn-managed content and refuses unmanaged directories:

norn skills uninstall --agent codex
norn skills uninstall --agent claude
norn skills uninstall --agent all

Use with Codex

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.

Use with Claude Code

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.

Consent and host permission

The managed workflow keeps two permissions separate:

1. Diff-sharing consent allows Norn to send only the selected diff and its review instructions to the configured AI provider.
2. Host permission lets the local norn review process run outside the coding agent sandbox so it can reach the provider CLI, configuration, OS credential store, and network.

For automatic post-task and pre-push review, the skill relies on a persisted local choice:

norn setup --allow-provider-diff --yes

For an explicit review that has not been authorized persistently, the agent adds --allow-provider-diff for that run only after you approve the exact target. Codex requests escalated or outside-sandbox execution for the exact norn review command. Claude Code requests the equivalent narrow Bash permission. The skill never edits agent settings, grants broad shell access, or reuses one-run consent for a different target.

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.

Machine-readable failures include review.diffConsentRequired, review.sandboxRestricted, and review.providerTimeout. The agent stops the gate and reports these conditions instead of copying the diff into another tool or treating the review as successful.

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.