Getting Started

Install brunnr, scan your first skill, and understand the output.

Installation

brunnr is a Python package with zero core dependencies. It requires Python 3.12 or later.

# pip
pip install brunnr

# pipx (isolated environment)
pipx install brunnr

# uv
uv pip install brunnr

If you plan to use the eval command (LLM-based skill evaluation), install with the eval extra:

pip install brunnr[eval]

This adds the anthropic SDK as a dependency. You will also need an ANTHROPIC_API_KEY environment variable set.

From source

git clone https://github.com/Peleke/brunnr.git
cd brunnr
pip install -e .

The flow

The typical brunnr workflow: install, scan your skills directory, review results.

01 · INSTALL pip install brunnr zero deps 02 · SCAN brunnr scan skills/ 7+1 classes 03 · REVIEW CLEAN / FLAG / BLOCK exit codes

Your first scan

brunnr scans SKILL.md files for security threats. If you have a skills/ directory, it will find them automatically.

brunnr scan

If your skills are elsewhere, pass the path:

brunnr scan path/to/skills/

You can also scan a single file:

brunnr scan my-skill/SKILL.md

Understanding the output

=== brunnr scan ===

  CLEAN  ax-rubric

  Scanned 1 files: 1 clean, 0 flagged, 0 blocked

Each file gets one of three verdicts:

Verdict Meaning Exit code
CLEAN No threats detected. Safe to use. 0
FLAG Suspicious patterns found. Review recommended. 0 (or 1 with --strict)
BLOCK Dangerous patterns detected. Do not use. 1

For more detail, add -v (verbose):

brunnr scan -v
=== brunnr scan ===

  FLAG   suspicious-skill -- 2 findings
         FLAG: [supply_chain] custom PyPI index (not pypi.org)
               --index-url https://evil.example.com/simple
         FLAG: [steganographic] zero-width character U+200B
               ...some hidden​text...

  Scanned 1 files: 0 clean, 1 flagged, 0 blocked

Install a skill

Browse available skills:

brunnr install --list
Available skills:
  - ax-rubric

Install one:

brunnr install ax-rubric

brunnr shows you the first 30 lines of the SKILL.md before installing. Review the content, then confirm:

--- ax-rubric/SKILL.md (first 30 of 142 lines) ---
---
name: ax-rubric
description: Score agent-facing tool descriptions against the AX Description Rubric...
---
...

Full source: https://github.com/Peleke/brunnr/tree/main/skills/ax-rubric

Install ax-rubric to ./skills/ax-rubric/? [y/N] y
  -> skills/ax-rubric/SKILL.md (142 lines)

Installed ax-rubric to ./skills/ax-rubric/

Tip: Run `brunnr eval ax-rubric --dry-run` to validate locally.

Run an eval

If the skill has test fixtures (in tests/<slug>/test-spec.json), you can validate it:

# Dry run: validate fixtures without API calls
brunnr eval ax-rubric --dry-run

# Full run: call Claude and check assertions
brunnr eval ax-rubric
=== brunnr eval: ax-rubric ===
  2 test cases, model: claude-sonnet-4-20250514

  [case-1] Score a bad description
    PASS: [score_range] Score 1 in [1, 2]
    PASS: [has_table] Table found
    PASS: [has_rewrite] Rewrite found

  [case-2] Score a good description
    PASS: [score_range] Score 5 in [4, 5]

=== 2/2 passed ===

What's next