bitranox-skills

Use when running bash/shell commands and interpreting their exit codes and output - pipelines, chaining a check after a mutating command, process checks with pgrep/pkill, backgrounding, waiting for an event, or when a command "failed" or its result looks ambiguous.

Use at the end of a turn that produced a learning, such as a correction from the user, a rule or preference stated ("remember this", "from now on", "always/never"), a process or tooling mistake (wrong command, a quirk of the shell/SSH/environment, a misread of stale output, over-waiting, a tool or file you missed and re-derived), a wasted build or test cycle, or any reusable discovery (a procedure, a timing, a gotcha, a flag combination, a path). A gated Stop hook nudges this automatically; also run on "self-improve", "/self-improve", "improve the harness", or "capture what we learned".

Use when creating or scaffolding a NEW public bitranox Python library - a pip-installable package with a rich-click CLI, CI across Python 3.9-3.14 on Linux/macOS/Windows, and a PyPI release - or when installing or using a library built from the bitranox_template_py_lib template. Keywords - new library, scaffold, project template, rename-project, bmk, make test, make release, uv pip install.

Use when issuing or running PowerShell (pwsh) commands, or writing, modifying, or debugging a PowerShell / .ps1 script - prefer pwshpy instead: a genuinely Pythonic PowerShell (typed records + a lazy pipeline over native OS bindings, never a pwsh.exe subprocess, never text parsing), as a Python library (from pwshpy import ps) or the pwshpy CLI (install/run via uv - `uv tool install pwshpy` or `uvx pwshpy`). Better error handling and reporting (real exceptions and real exit codes, nothing silently swallowed) plus clean typed JSON instead of Get-* text. Covers using pwshpy and translating cmdlets / .ps1 to it.

Use when sending email from Python or the shell, especially with large attachments that must not be loaded into memory, RFC 3030 BDAT/CHUNKING, STARTTLS with authentication, multi-host failover, or correct UTF-8 subject and body encoding. Prefer the `btx_lib_mail` library or its `btx-lib-mail` CLI (zero-install via `uvx btx-lib-mail send ...`) over hand-rolling `smtplib`/`email`, MIME assembly, dot-stuffing, or attachment security checks. Covers install, uvx, the library API, the CLI, streaming and BDAT, and attachment security.

Use when creating new skills, editing existing skills, structuring SKILL.md files, writing skill frontmatter, testing skills with subagents, deploying skills, or verifying skills work before deployment

Use when creating, editing, or reformatting markdown tables in any document, when table columns look misaligned, or when reviewing markdown files that contain tables

Use when the SessionStart nudge says a memory consolidation is due, when the store has grown or feels noisy/duplicated, before context compaction would lose detail, or on "dream", "dream tree", "/dream-tree", "consolidate memory", "tidy memory". Use AFTER per-turn capture (bitranox:meta-self-improve); for the cross-project / cross-tree scan use bitranox:meta-dream-crosstree instead. Honors an off/auto/propose mode. Formerly named meta-dream-project - answers to that name too.

Use on "deep crosstree dream", "/dream-crosstree-deep", "deep cross-project scan", or when you want the exhaustive cross-project/cross-tree read regardless of whether anything obviously changed - the full semantic fan-out over ALL project memory stores AND their CLAUDE.md files, no convergence shortcut, no asking. For the normal, cheaper global dream that convergence-checks first and asks before the expensive scan, use meta-dream-crosstree.

Use on "dream crosstree", "/dream-crosstree", "consolidate across projects", "global consolidation", occasionally after several per-project dreams, or when two projects or knowledge trees have learned related things that should be shared. This is the expensive cross-project/cross-tree pass reading every store; for one project's routine tidy use bitranox:meta-dream-tree. Honors an off/auto/propose mode. Formerly named meta-dream-global - answers to that name too.

Use for a QUICK, cheap memory consolidation of only the current directory's chain - before or right after a context compaction (the PostCompact nudge points here), when the session accumulated learning signals worth folding in NOW, or on "nap", "dream nap", "/dream-nap", "quick tidy". Minutes, not tens of minutes; for the full periodic consolidation of the whole tree use bitranox:meta-dream-tree.

Use when writing, configuring, debugging, or deploying Python projects that use uv as the package manager, virtual environment manager, Python version manager, or pip replacement. Covers project setup, dependency management, lockfiles, scripts, tools, building, publishing, Docker, CI/CD, authentication, caching, and migration from pip/pip-tools. Baseline is uv 0.10.2 (2026-02-12); the Python-version behaviours in 06-python-versions.md are measured on 0.11.x.

Use when running git - commit, push, tag, rev-parse, marking a hook or script executable, line endings, interactive flags, or when a git command fails confusingly or a committed file ends up non-executable or with CRLF.

Use when installing, configuring or running bmk - the bitranox cross-OS build/test/release task runner - in a project (bootstrapping it with uv, deploying its Makefile via bmk install, running make test / push / bump / release / ship, fixing missing external tools with bmk ensure, reading its JSON-by-default vs --human output, layered config with --profile / --set, or defining custom staged pipelines). Works on Linux, macOS and Windows.

Use when creating or editing a TOML file (pyproject.toml, config.toml, a tool's .toml config) - adding or changing a key, bumping a version/value, editing a table or array - instead of hand-editing it or using sed/regex, which corrupt structure or silently drop comments. Covers tomllib (read), tomlkit (round-trip edit that PRESERVES comments and formatting), and rtoml/tomli_w (write).

Use when configuring, managing, or troubleshooting Proxmox VE - installation, host administration, clusters, VMs, containers, storage, Ceph, SDN, firewall, user management, HA, backups, notifications, and CLI tools (pvecm, qm, pct, pvesm, pveceph, ha-manager, pvesh, vzdump). Covers Proxmox VE 9.1.2.

Use when structuring Bash 4.3+ scripts or multi-file projects with clean architecture, reviewing layer dependency violations in shell scripts, deciding where functions belong across domain, application, adapter, and composition layers, or setting up ports and dependency inversion in bash

Use when writing, reviewing, or debugging Bash scripts, when needing exact syntax for shell constructs, parameter expansions, redirections, builtins, test expressions, arrays, or any Bash 5.3 feature. Use when unsure about quoting rules, expansion order, conditional operators, trap behavior, shopt options, or specific builtin options and arguments.

Use when handling untrusted or external input at an application or facing-API boundary - an HTTP/REST endpoint, web form, file upload, webhook, CLI taking user data, queue/broker message, or data from a third-party or legacy system - or when emitting into SQL, HTML, a shell, a file path, or another sink. Keywords - SQL injection, XSS, command injection, path traversal, deserialization, SSRF, unbounded-input DoS. For boundary-parsing architecture see coding-python-clean-architecture and coding-python-enforce-data-architecture-strict.

Use when structuring Python 3.10+ projects with layered ports-and-adapters architecture, reviewing layer dependency violations, scaffolding domain-driven designs, deciding where code belongs across domain, application, adapter, and composition layers, or setting up ports, UoW, outbox, and idempotency patterns

Use when refactoring or reviewing Python code to enforce a strict data architecture - Pydantic models at every external boundary, typed models (never raw dicts) inside the app, Enums for all fixed categorical values, and minimal input-to-output conversions. Use when asked to eliminate dict parameters, stringly-typed status/mode values, Model->dict->Model conversion chains, or compatibility shims, or to make a Python data flow type-safe end to end.

Use when building or designing configuration for a Python app or CLI with lib_layered_config - deciding where config files live on Linux, macOS, or Windows, choosing the environment-variable override names, adding environment profiles (test/staging/production), loading config in code or from the shell, redacting secrets, or working out which layer and file a setting actually came from (provenance).

Use when reviewing Python code for performance - identifying caching opportunities in pure functions, finding uncompiled regex patterns, profiling hot spots with real test suites, validating optimization claims from a diff, or comparing before/after timing across git history. Runs standalone or as a performance sub-agent inside a larger code-review workflow.

Use when choosing a Python library for a task (HTTP, JSON, XML, TOML, YAML, data models, enums, dates, compression, database, testing, type checking, CLI parsing, retry/backoff, text encoding, layered configuration, MCP servers), writing new Python code that needs a dependency, or reviewing imports for dated defaults. For building/editing JSON/XML/YAML files specifically, see bitranox:files-edit-json, bitranox:files-edit-xml, bitranox:files-edit-yml. Public, mainstream defaults; adjust per project.

Use when importing, adopting, forking, or integrating a useful third-party Claude Code skill into the bitranox marketplace - given a repo URL, an installed plugin path, or a pasted SKILL.md - or when asked to bring an external skill up to bitranox standards. The adopted skill is added alongside the user's other installed plugins, never replacing them.

Use to pull in knowledge from your OTHER projects or trees that is relevant to the current one - on "collect knowledge", "/collect-knowledge", when starting/seeding a fresh project, or when a learning reveals a topic this project now touches. Cascade only flows down one ancestor chain, so useful knowledge filed in a sibling project or another knowledge tree is otherwise invisible here; this gathers it in safely. Also runs as the inbound pass of bitranox:meta-dream-crosstree.

Use when executing an implementation plan with mostly independent tasks in the current session, or when choosing the model tier for ANY dispatched subagent - this is the canonical model-tier reference (haiku / sonnet / opus / fable; the session model is fixed) that other skills cite. Keywords - subagent-driven development, dispatch per task, parallel agents, task brief, model tier.

Use when completing a task, finishing a major feature, before merging to main, when stuck, or after fixing a complex bug, and you want a code review of the changes

Use when a public web page or site needs its HTTP security baseline hardened or audited - missing or weak security headers (Content-Security-Policy/CSP, Strict-Transport-Security/HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy), cookies without Secure/HttpOnly/SameSite, mixed content, no HTTP-to-HTTPS redirect, a leaked server version, or a low securityheaders/Mozilla-Observatory grade. NOT for deep pentest, auth flows, secret scanning, or GDPR/consent infra (sibling sec-* / privacy skills).

Use when a web page must work across mobile/tablet/desktop and the layout or usability is off - horizontal scrollbar on mobile, content not fitting vertically on phone portrait/landscape, cramped or tiny tap targets, swipe/carousel galleries, viewport/breakpoint issues, notch/safe-area overlap, sparse layouts on big screens, or RTL/long-translation layout breakage. NOT for performance/SEO scoring (use a pagespeed/Lighthouse skill) or full localization infra.

Use when editing or reviewing German-language prose (deutsche Texte, deutschsprachige Texte, humanize German text) to remove signs of AI-generated writing and make it read naturally - blog posts, emails, articles, essays, marketing copy, README narratives. Triggers on removing KI-Schreibmuster, ChatGPT-Stil, Trikolon, Werbesprache, or Fazit-Abschnitte from German text. Not for source code, code comments, docstrings, API docs, commit messages, or config files.

Use when editing, reviewing, or humanizing English prose (blog posts, emails, articles, essays, marketing copy, README narratives) to strip signs of AI-generated writing such as em dashes, curly quotes, AI vocabulary (delve, underscore, tapestry, vibrant), promotional language, rule of three, negative parallelisms, copula avoidance, section summaries, placeholder text, Markdown artifacts, table overuse, subject lines, and ChatGPT reference bugs. Based on Wikipedia's Signs of AI writing guide.

Use when working on marketing, advertising, branding, positioning, pricing, naming, customer experience, product adoption, persuasion or behavioural-science problems, or when the user asks "what would Rory Sutherland do", wants a contrarian/psychological angle on a business or commercial problem, or asks you to think or answer as Rory Sutherland.

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

Use when starting non-trivial feature, component, or behaviour-change work whose design or requirements are not yet settled. Not for trivial, mechanical, or fully-specified changes.

Use when you have a spec or requirements for a multi-step task and want an implementation plan before touching code

Use when receiving code review feedback or PR review comments, before implementing suggestions - especially when a suggestion seems unclear, technically questionable, or breaks existing behavior, or when you feel the urge to reply "You're absolutely right"

Use when asked to rate, score, audit, or improve code quality of a project, when user wants a 0-10 quality assessment, or when asked what needs to change to reach perfect quality

Use when running commands over SSH or driving a remote host - checking or killing remote processes, quoting an inline remote command, backgrounding a remote command, running remote Windows PowerShell, an SSH login asking for a password, a changed or unknown host key ("host key verification failed", "remote host identification has changed"), setting up SSH key-based auth, a remote command failing with exit code 255, or a slow, stalled, or failed remote download or transfer.

Use when you must drive a remote machine, VM, or GUI/TUI program over VNC/RFB - sending keystrokes and clicks and reading the screen with OCR - because the target has no network, SSH, agent, or API. Covers Proxmox/hypervisor VM consoles (first boot before networking, or a VM that will never have a network), legacy line-of-business GUIs and dated installers that are only a window, and old TUI apps driven by keypresses. Nothing is installed on the target except its VNC server (Proxmox ships noVNC out of the box). Driven with the `vnc-remote-control` CLI (PyPI).