brunnr 0.1.0__tar.gz

brunnr-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,29 @@
+{
+  "name": "brunnr-skills",
+  "owner": {
+    "name": "Peleke Sengstacke",
+    "email": "peleke@hey.com"
+  },
+  "metadata": {
+    "description": "Security-scanned agent skills from the brunnr registry. Every skill passes a 7-class deterministic security scanner before distribution.",
+    "version": "0.1.0",
+    "pluginRoot": "./skills"
+  },
+  "plugins": [
+    {
+      "name": "ax-rubric",
+      "source": "ax-rubric",
+      "description": "Score agent-facing tool descriptions 0-5 on discoverability. Takes a tool description, explains failures against 5 criteria, and rewrites it to pass.",
+      "version": "1.0.0",
+      "author": {
+        "name": "Peleke Sengstacke"
+      },
+      "homepage": "https://peleke.github.io/brunnr/skills/ax-rubric/",
+      "repository": "https://github.com/Peleke/brunnr",
+      "license": "MIT",
+      "keywords": ["agent-tools", "mcp", "discoverability", "scoring", "tool-descriptions"],
+      "category": "code-quality",
+      "tags": ["ax", "rubric", "agent-experience", "mcp-tools"]
+    }
+  ]
+}

brunnr-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install mkdocs dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Build docs
+        run: mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

brunnr-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,84 @@
+name: "Publish: brunnr"
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[eval]" pytest
+      - run: python -m pytest tests/ -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  release:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Generate changelog
+        id: changelog
+        run: |
+          # Find the previous tag
+          PREV_TAG=$(git tag --sort=-v:refname | head -2 | tail -1)
+          if [ "$PREV_TAG" = "${{ github.ref_name }}" ] || [ -z "$PREV_TAG" ]; then
+            # First release — changelog from all commits
+            echo "## What's Changed" > RELEASE_NOTES.md
+            git log --pretty=format:"- %s (%h)" >> RELEASE_NOTES.md
+          else
+            echo "## What's Changed" > RELEASE_NOTES.md
+            git log "${PREV_TAG}..HEAD" --pretty=format:"- %s (%h)" >> RELEASE_NOTES.md
+          fi
+          echo "" >> RELEASE_NOTES.md
+          echo "**Full Changelog**: https://github.com/${{ github.repository }}/compare/${PREV_TAG:-initial}...${{ github.ref_name }}" >> RELEASE_NOTES.md
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            --title "${{ github.ref_name }}" \
+            --notes-file RELEASE_NOTES.md \
+            dist/*

brunnr-0.1.0/.github/workflows/test-skills.yml

@@ -0,0 +1,254 @@
+name: Skill Tests
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  security-scan:
+    name: Security Scan (7-class)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Scan all SKILL.md files
+        run: python3 tests/scan-all-skills.py --strict
+
+      - name: Upload scan report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: scan-report
+          path: tests/artifacts/scan-report.json
+
+      - name: Post scan summary
+        if: always()
+        run: |
+          echo "## Security Scan Results" >> $GITHUB_STEP_SUMMARY
+          python3 -c "
+          import json
+          report = json.load(open('tests/artifacts/scan-report.json'))
+          total = report['total']
+          blocked = report['blocked']
+          flagged = report['flagged']
+          clean = report['clean']
+          print(f'| Metric | Count |', file=open('$GITHUB_STEP_SUMMARY', 'a'))
+          print(f'|--------|-------|', file=open('$GITHUB_STEP_SUMMARY', 'a'))
+          print(f'| Scanned | {total} |', file=open('$GITHUB_STEP_SUMMARY', 'a'))
+          print(f'| Clean | {clean} |', file=open('$GITHUB_STEP_SUMMARY', 'a'))
+          print(f'| Flagged | {flagged} |', file=open('$GITHUB_STEP_SUMMARY', 'a'))
+          print(f'| Blocked | {blocked} |', file=open('$GITHUB_STEP_SUMMARY', 'a'))
+          if blocked > 0:
+              print(f'', file=open('$GITHUB_STEP_SUMMARY', 'a'))
+              print(f'**{blocked} skill(s) BLOCKED by security scanner.**', file=open('$GITHUB_STEP_SUMMARY', 'a'))
+              for s in report['skills']:
+                  if s['blocked']:
+                      findings = ', '.join(f['desc'] for f in s['findings'] if f['severity'] == 'block')
+                      print(f'- **{s[\"file\"]}**: {findings}', file=open('$GITHUB_STEP_SUMMARY', 'a'))
+          "
+
+  frontmatter-lint:
+    name: Lint SKILL.md Frontmatter
+    needs: [security-scan]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate all SKILL.md files
+        run: |
+          echo "=== SKILL.md Frontmatter Validation ==="
+          ERRORS=0
+          TOTAL=0
+
+          for skill_md in skills/*/SKILL.md; do
+            [ -f "$skill_md" ] || continue
+            TOTAL=$((TOTAL + 1))
+            SKILL_DIR=$(dirname "$skill_md")
+            SKILL_SLUG=$(basename "$SKILL_DIR")
+
+            # Extract frontmatter (between --- lines)
+            FRONTMATTER=$(sed -n '/^---$/,/^---$/p' "$skill_md" | sed '1d;$d')
+
+            NAME=$(echo "$FRONTMATTER" | grep "^name:" | sed 's/^name: *//')
+            DESC=$(echo "$FRONTMATTER" | grep "^description:" | head -1)
+
+            if [ -z "$NAME" ]; then
+              echo "FAIL: $skill_md — missing 'name' in frontmatter"
+              ERRORS=$((ERRORS + 1))
+            elif [ "$NAME" != "$SKILL_SLUG" ]; then
+              echo "FAIL: $skill_md — name '$NAME' does not match directory '$SKILL_SLUG'"
+              ERRORS=$((ERRORS + 1))
+            else
+              echo "OK: $NAME"
+            fi
+
+            if [ -z "$DESC" ]; then
+              echo "FAIL: $skill_md — missing 'description' in frontmatter"
+              ERRORS=$((ERRORS + 1))
+            fi
+          done
+
+          echo ""
+          echo "=== $TOTAL skills checked, $ERRORS errors ==="
+
+          if [ $ERRORS -gt 0 ]; then
+            exit 1
+          fi
+
+  discover-skills:
+    name: Discover Testable Skills
+    needs: [security-scan]
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.discover.outputs.matrix }}
+      has_tests: ${{ steps.discover.outputs.has_tests }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Find skills with test suites
+        id: discover
+        run: |
+          SKILLS="[]"
+          HAS_TESTS="false"
+
+          for test_dir in tests/*/; do
+            [ -d "$test_dir" ] || continue
+            SKILL_SLUG=$(basename "$test_dir")
+
+            # Only include if the corresponding skill exists
+            if [ -f "skills/$SKILL_SLUG/SKILL.md" ] && [ -f "$test_dir/test-spec.json" ]; then
+              SKILLS=$(echo "$SKILLS" | python3 -c "
+          import json, sys
+          arr = json.load(sys.stdin)
+          arr.append('$SKILL_SLUG')
+          json.dump(arr, sys.stdout)
+          ")
+              HAS_TESTS="true"
+            fi
+          done
+
+          echo "matrix={\"skill\":$SKILLS}" >> "$GITHUB_OUTPUT"
+          echo "has_tests=$HAS_TESTS" >> "$GITHUB_OUTPUT"
+          echo "Discovered skills with tests: $SKILLS"
+
+  eval-skills:
+    name: "Eval: ${{ matrix.skill }}"
+    needs: [frontmatter-lint, discover-skills]
+    if: needs.discover-skills.outputs.has_tests == 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.discover-skills.outputs.matrix) }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pip install anthropic pyyaml
+
+      - name: "Run evals for ${{ matrix.skill }}"
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          python tests/harness.py \
+            --skill "${{ matrix.skill }}" \
+            --output "tests/${{ matrix.skill }}/results.json"
+
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: eval-results-${{ matrix.skill }}
+          path: tests/${{ matrix.skill }}/results.json
+
+  eval-summary:
+    name: Eval Summary
+    needs: [eval-skills]
+    if: always() && needs.eval-skills.result != 'skipped'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: eval-results-*
+          merge-multiple: true
+          path: eval-results/
+
+      - name: Summarize results
+        run: |
+          echo "## Skill Eval Results" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Skill | Pass | Fail | Total | Result |" >> $GITHUB_STEP_SUMMARY
+          echo "|-------|------|------|-------|--------|" >> $GITHUB_STEP_SUMMARY
+
+          OVERALL_PASS=true
+
+          for result_file in eval-results/*/results.json; do
+            [ -f "$result_file" ] || continue
+            SKILL=$(python3 -c "import json; r=json.load(open('$result_file')); print(r['skill'])")
+            PASS=$(python3 -c "import json; r=json.load(open('$result_file')); print(r['summary']['pass'])")
+            FAIL=$(python3 -c "import json; r=json.load(open('$result_file')); print(r['summary']['fail'])")
+            TOTAL=$(python3 -c "import json; r=json.load(open('$result_file')); print(r['summary']['total'])")
+            OK=$(python3 -c "import json; r=json.load(open('$result_file')); print('Pass' if r['summary']['fail']==0 else 'FAIL')")
+
+            if [ "$OK" = "FAIL" ]; then
+              OVERALL_PASS=false
+            fi
+
+            echo "| $SKILL | $PASS | $FAIL | $TOTAL | $OK |" >> $GITHUB_STEP_SUMMARY
+          done
+
+          if [ "$OVERALL_PASS" = "false" ]; then
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "**One or more skill evals failed.**" >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
+
+  schema-check:
+    name: Validate Output Schemas
+    needs: [security-scan]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install ajv-cli
+        run: npm install -g ajv-cli ajv-formats
+
+      - name: Validate per-skill output schemas
+        run: |
+          echo "=== Output Schema Validation ==="
+          ERRORS=0
+
+          for schema_file in schemas/*/output.schema.json; do
+            [ -f "$schema_file" ] || continue
+            SKILL=$(basename "$(dirname "$schema_file")")
+
+            echo "Validating schema for $SKILL..."
+            if ajv compile -s "$schema_file" --strict=false 2>/dev/null; then
+              echo "OK: $SKILL schema is valid JSON Schema"
+            else
+              echo "FAIL: $SKILL schema is not valid JSON Schema"
+              ERRORS=$((ERRORS + 1))
+            fi
+          done
+
+          if [ $ERRORS -gt 0 ]; then
+            echo "ERROR: $ERRORS invalid schemas"
+            exit 1
+          fi
+
+          echo "All schemas valid."

brunnr-0.1.0/.github/workflows/trigger-skillipedia.yml

@@ -0,0 +1,22 @@
+# When skills change on main, trigger a Skillipedia site rebuild.
+# Requires CROSS_REPO_TOKEN secret with repo dispatch permissions.
+name: Trigger Skillipedia Rebuild
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'skills/**'
+  workflow_dispatch:
+
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dispatch to Skillipedia
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.CROSS_REPO_TOKEN }}
+          repository: Peleke/skillipedia
+          event-type: brunnr-skills-updated
+          client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}'

brunnr-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+site/
+dist/

brunnr-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to brunnr will be documented in this file.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-11
+
+### Added
+- `brunnr scan` — pattern-based security scanner for agent tool descriptions (SKILL.md files)
+- `brunnr install` — fetch and install skills from the brunnr registry with review-before-install
+- `brunnr eval` — LLM-graded evaluation of tool descriptions against the ax-rubric
+- `brunnr pipeline` — combined scan + eval in a single pass
+- 26 built-in scan rules across 5 categories (prompt-injection, over-privilege, data-leak, ambiguity, missing-constraint)
+- `ax-rubric` skill — score tool descriptions 0-5 on discoverability
+- Claude Code plugin marketplace support (`.claude-plugin/marketplace.json`)
+- Path traversal protection in install command
+- MkDocs documentation site with ReadTheDocs theme
+- PyPI publishing via OIDC trusted publisher (tag-triggered)
+- GitHub Release with auto-generated changelog on tag push
+- 74 tests (55 scanner + 19 CLI)
+
+[Unreleased]: https://github.com/Peleke/brunnr/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Peleke/brunnr/releases/tag/v0.1.0

brunnr-0.1.0/Dockerfile.scanner

@@ -0,0 +1,6 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY bin/ bin/
+COPY tests/ tests/
+COPY skills/ skills/
+CMD ["python3", "tests/scan-all-skills.py", "--json"]

brunnr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peleke Sengstacke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brunnr-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: brunnr
+Version: 0.1.0
+Summary: Security scanner and skill registry for agent tool descriptions
+Author: Peleke Sengstacke
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Provides-Extra: eval
+Requires-Dist: anthropic>=0.40; extra == 'eval'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="assets/hero.png" alt="brunnr — the well agents drink from" width="100%" />
+
+# brunnr
+
+**The well agents drink from.**
+
+*Skills marketplace for Claude Code and agent-facing tools.*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Skills](https://img.shields.io/badge/skills-1-4ade80)](skills/)
+[![AX Rubric](https://img.shields.io/badge/ax--rubric-v1.0-e88072)](skills/ax-rubric/)
+
+</div>
+
+---
+
+> *Beneath the world tree there is a well. Odin gave an eye to drink from it.*
+>
+>*Your agent won't need to. We bottled the water.*
+
+---
+
+## Contents
+
+- [AX Description Rubric](#ax-description-rubric) — score your tool descriptions
+- [Install](#install) — one command
+- [What you get](#what-you-get) — example output
+- [The Rubric](#the-rubric) — five criteria, explained
+- [Skills](#skills) — what's available
+- [Why "brunnr"](#why-brunnr)
+- [Contributing](#contributing)
+
+---
+
+## What this is
+
+**brunnr** is a skills marketplace for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Install it once, get access to every skill in the collection.
+
+### AX Description Rubric
+
+The first skill: the **AX Description Rubric** — a tool that scores your agent-facing tool descriptions against [five criteria](https://peleke.me/writing/ax-04-tool-descriptions) that determine whether an agent will ever call your tool.
+
+Most tool descriptions score 1-2 out of 5. The rubric tells you why, then rewrites them to score 5.
+
+## Install
+
+```bash
+# Add the marketplace
+/plugin marketplace add Peleke/brunnr
+
+# Use the skill
+/ax-rubric
+```
+
+Paste your tool description when prompted. Or pass it inline:
+
+```
+/ax-rubric "Query the knowledge base for structured learnings, patterns, and skills relevant to your current work context."
+```
+
+## What you get
+
+#### `knowledge_base_query`
+
+**Score: 1/5**
+
+| Criterion | Result | Notes |
+|-----------|--------|-------|
+| Output shape | fail | "structured learnings, patterns, and skills" — how many? |
+| Cost signal | fail | No indication of response size |
+| Trigger clarity | fail | "relevant to your current work context" — always true |
+| Specificity | fail | Lists categories, solves no named problem |
+| Differentiation | fail | Half your tools say "relevant to current context" |
+
+**Rewritten (5/5):**
+
+> "Check for known pitfalls before starting work. Returns 3-5 specific warnings for your tech stack. ~500 tokens. Call once at session start."
+
+One input, five scores, one rewrite. The rewrite is ready to paste into your tool definition.
+
+---
+
+## The rubric
+
+Five criteria. Binary pass/fail. Most descriptions fail.
+
+<img src="assets/rubric.svg" alt="The AX Description Rubric — five criteria for agent-facing tool descriptions" width="100%" />
+
+**0-1 pass** = invisible (agent will never call it). **2-3** = marginal. **4-5** = habitual.
+
+The bar for habitual use is 4/5. Most tool descriptions in the wild score 1-2. The tool might be excellent. The agent will never know.
+
+---
+
+## Skills
+
+| Skill | What it does | Based on |
+|-------|-------------|----------|
+| **[ax-rubric](skills/ax-rubric/)** | Score tool descriptions for agent discoverability. 5 criteria, pass/fail, rewrite. | [I Don't Deliberate About This](https://peleke.me/writing/ax-04-tool-descriptions) |
+
+More skills coming. Each one ships alongside an article in the [AX series](https://peleke.me/writing/ax-series).
+
+---
+
+## Why "brunnr"
+
+Old Norse *brunnr*: well, spring.
+
+As in *Mímisbrunnr* — the Well of Mímir beneath Yggdrasil. Odin sacrificed an eye to drink from it and gain wisdom. The well doesn't give you answers. It gives you the capacity to see what was always there.
+
+Your agent doesn't need to sacrifice anything. It just needs tool descriptions that don't waste its context window.
+
+---
+
+## Contributing
+
+Have an agent-facing tool? Run `/ax-rubric` on your own descriptions first. If they score 4+, you're ahead of 90% of the field.
+
+Want to add a skill? Open a PR. The rubric applies to skill descriptions too.
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+<div align="center">
+
+*Part of the [Agent Experience (AX)](https://peleke.me/writing/ax-series) series*
+*by [Peleke Sengstacke](https://peleke.me) and [Maren](https://peleke.me/writing/ax-01a-the-agent-has-opinions).*
+
+</div>