Getting it into your agent
It runs from inside its repository, so the clone comes first — what it calls does not travel with the file alone.
git clone --depth 1 https://github.com/BESSER-PEARL/BESSER-Skillsnpx agentmods add skills/besser-pearl/besser-skills/besser-troubleshootingWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/besser-pearl/besser-skills/besser-troubleshooting)<a href="https://agentmods.dev/skills/besser-pearl/besser-skills/besser-troubleshooting"><img src="https://agentmods.dev/badge/skills/besser-pearl/besser-skills/besser-troubleshooting/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/besser-pearl/besser-skills/besser-troubleshooting"><img src="https://agentmods.dev/badge/skills/besser-pearl/besser-skills/besser-troubleshooting.svg" alt="Reviewed on agentmods" width="80" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00306 | $0.04176 |
| Opus 5 | $0.00153 | $0.02088 |
| Sonnet 5 | $0.00061 | $0.00835 |
| Haiku 4.5 | $0.00031 | $0.00418 |
Grade A, and why
besser-troubleshooting scanned grade A with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 12d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Runs shell commandslowCapability
Expected in a hook, worth knowing in a rule or an instructions file.
subprocess.CalledProcessError, or any other failure originating from How it starts
The opening of the file, as written. The whole thing — 419 lines — stays where its author put it; the contents beside it link to each section on GitHub.
BESSER Troubleshooting
Quick reference for diagnosing and fixing common issues. Organized by
symptom. This is an intentionally flat, single-file skill — a fast lookup
you scan top-to-bottom or search, with no references/ subdirectory.
Installation Issues
pip install besser fails with native dependency errors
Several BESSER dependencies require system libraries:
| Dependency | Requires | Fix (Ubuntu/Debian) | Fix (macOS) |
|---|---|---|---|
psycopg2-binary |
PostgreSQL client libs | apt install libpq-dev |
brew install postgresql |
pyodbc |
ODBC driver manager | apt install unixodbc-dev |
brew install unixodbc |
oracledb |
Oracle Instant Client | Download from Oracle | Download from Oracle |
If you don't need a specific database, these won't block core BESSER functionality — most generators work fine with SQLite (no native deps needed).
pip install -e . fails or installs nothing
- Must be run from the repository root (where
setup.cfgandpyproject.tomllive;setup.cfgholds the package metadata andpython_requires). - Requires
setuptools>=42andwheel. Upgrade first:pip install --upgrade setuptools wheel. - Check you're in the right virtual environment:
which python(Unix) orwhere python(Windows).
Python version incompatibility
BESSER requires Python 3.11+ (enforced by python_requires = >=3.11 in setup.cfg). Check with:
python --version
If you're on 3.10 or earlier, upgrade Python or use pyenv/conda to manage versions.
Windows-specific: venv\Scripts\activate not found
The activation path is venv\Scripts\activate (capital S). A common mistake in
some docs is venv\Script\activate (missing the 's') — this will fail.
:: Correct:
venv\Scripts\activate
Import Errors
ModuleNotFoundError: No module named 'besser'
- Not installed: Run
pip install -e .from the repo root, orpip install besser. - Wrong environment: Activate your venv first (
source venv/bin/activateorvenv\Scripts\activate). - Multiple Python installs:
pipandpythonmay point to different installations. Usepython -m pip install -e .to ensure alignment.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 12d ago First seen · 419 lines · 306 tokens per session scan A 94d7fe7f6c03
besser-troubleshooting is a skill published in the GitHub repository BESSER-PEARL/BESSER-Skills (8 stars, last pushed yesterday), licensed Apache-2.0. It adds 306 tokens to every session and 4,176 once invoked, about $0.0015 per session on Opus 5. A static security scan graded it A with 1 finding (runs shell commands). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other skills, from other repositories
systematic-debugging
4-phase root cause debugging: understand bugs before fixing.
langsmith-observability
LLM observability platform for tracing, evaluation, and monitoring. Use when debugging LLM applications, evaluating model outputs against datasets, monitoring production systems, or building systematic testing pipelines for AI applications.
browser-edge-cases
SOP for debugging browser automation failures on complex websites. Use when browser tools fail on specific sites like LinkedIn, Twitter/X, SPAs, or sites with Shadow DOM.
ha-logs
A read-only troubleshooting skill for querying Hope Agent’s local SQLite databases, which store logs, conversations, and background-job status.
bug-triage
Read all open bugs in production/qa/bugs/, re-evaluate priority vs. severity, assign to sprints, surface systemic trends, and produce a triage report. Run at sprint start or when the bug count grows enough to need re-prioritization.
bug-report
Creates a structured bug report from a description, or analyzes code to identify potential bugs. Ensures every bug report has full reproduction steps, severity assessment, and context.