overthinkos/debug-tools-layer
versa/skills/debug-tools-layer/SKILL.md
Debug toolkit for inspecting deployed services from inside the container — network probes (ip/ss/lsof/ping/dig/nc/socat/tcpdump/traceroute/mtr/wget), process inspection (ps/top/htop/pgrep/free/vmstat/strace/ltrace), file inspection (file/tree/xxd/vim/nano), system stats (iotop/iftop/sysstat), session helpers (tmux/rsync/yq). Distro-agnostic. Use when working with the debug-tools layer, the per-distro package-name divergence (nmap-ncat vs ncat vs gnu-netcat), or the 16 build-scope check probes that lock in headline binary presence.
tools
Updated Jun 15, 2026
$ install --global
skillsauthnpx skillsauth add overthinkos/overthink-plugins debug-tools-layerInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jun 15, 2026, 7:50 AM197.7s1 file scanned
SKILL.md
- name:
- debug-tools-layer
- description:
- |
debug-tools — distro-agnostic debug toolkit
Single-purpose layer that installs ~50 standard debugging utilities
across 5 categories: network, process, file, system stats, session
helpers. Composed by /charly-versa:versa so operators can debug
the deployed services (marimo, airflow, martin, maputnik, etc.) from
INSIDE the running container.
Without this layer, charly cmd versa "ps" returns
"command not found" — minimal Fedora images don't ship procps-ng,
iproute, bind-utils, etc. by default.
Layer properties
| Property | Value | |----------|-------| | Dependencies | none | | Distros | fedora, arch, debian, ubuntu (per-distro package lists) | | Ports | none | | Services | none | | Volumes | none | | Check probes | 16 build-scope (one per headline binary) |
Tool catalog
Network
ip, ss, netstat, lsof, ping, dig, nslookup, nc,
socat, tcpdump, traceroute, mtr, wget
Cover the full DNS / TCP / packet-capture / ICMP / port-relay surface.
curl already comes from elsewhere (jq layer dep), so wget
complements it.
Process
ps, top, htop, pgrep, pkill, kill, killall, pidof,
free, vmstat, watch, slabtop, strace, ltrace, iotop,
iftop
Process inspection (procps-ng) + system tracing (strace/ltrace) + I/O & network tops (iotop/iftop).
File / text
file, tree, vim, nano, xxd
xxd ships with vim-common (auto-installed alongside vim-enhanced).
System stats
sysstat package provides iostat, mpstat, pidstat, sar,
sadf — historical metrics + per-task accounting.
Session helpers
tmux, rsync, yq
Multi-pane shell sessions, file sync, YAML manipulation.
Per-distro package divergence
Tool names aren't portable — each distro is enumerated separately to avoid silent "installed nothing" on the wrong distro:
| Tool | fedora | arch | debian | ubuntu |
|---|---|---|---|---|
| Process basics (ps, top, free, kill, pgrep, vmstat) | procps-ng | procps-ng | procps | procps |
| ip + ss + tc | iproute | iproute2 | iproute2 | iproute2 |
| netstat + ifconfig | net-tools | net-tools | net-tools | net-tools |
| dig + nslookup + host | bind-utils | bind-tools | dnsutils | dnsutils |
| ping | iputils | iputils | iputils-ping | iputils-ping |
| nc | nmap-ncat | gnu-netcat | ncat | ncat |
| traceroute | traceroute | traceroute | traceroute | traceroute |
| mtr | mtr | mtr | mtr-tiny | mtr-tiny |
| vim | vim-enhanced | vim | vim | vim |
| yq | yq (Fedora py) | go-yq (mikefarah Go) | (omitted — snap-only) | (omitted) |
Single common name (socat, tcpdump, lsof, file, tree,
nano, htop, strace, ltrace, iotop, iftop, sysstat,
tmux, rsync, wget) covers all four distros.
Check coverage (16 probes — locks in headline binaries)
Spot-checks one binary per category. If a future package rename breaks one, the build fails loudly at image build time:
ps-binary,ss-binary,lsof-binary,ping-binary,dig-binary,nc-binary,tcpdump-binary— network/process headlineshtop-binary,strace-binary— interactive/tracingvim-binary,nano-binary,tree-binary,file-binary— file/texttmux-binary,wget-binary,rsync-binary— session/transfer
ping-binary and nc-binary are checked via command -v rather
than file path because the binary's location varies across distros
(Fedora: /usr/bin/ping; Debian: /usr/bin/ping but historically
/bin/ping).
Use case: debugging versa services
| Scenario | Tools |
|---|---|
| "Is martin actually listening on 3000?" | ss -tlnp \| grep 3000, lsof -i :3000 |
| "What's the airflow scheduler doing?" | ps auxf \| grep airflow, htop, strace -p <pid> |
| "Is the marimo MCP responding?" | curl http://localhost:2718/mcp/server, nc -zv localhost 2718 |
| "Why is the GTFS download slow?" | iftop -i eth0, traceroute api.transitous.org |
| "Is the workspace volume filling up?" | du -sh /workspace/*, iotop |
| "What's eating CPU?" | htop, pidstat -u 1 |
Cross-references
/charly-versa:versa— image composing this layer/charly-versa:airflow-layer— services this toolkit debugs/charly-versa:osm-tools-layer— martin server this toolkit debugs/charly-versa:versa-layer— marimo runtime this toolkit debugs/charly-coder:dev-tools— overlapping but heavier (includes qemu, AWS CLI, etc.); not composed by versa
Related Skills
overthinkos/plugin
tools
VerifiedTrustedCommunity
Use when authoring or modifying a charly PLUGIN — a candy with a `plugin:` block that contributes Providers (verbs/kinds/deploy-targets/steps/builders/commands), its own CUE schema, builtin (compiled-in) or external (out-of-tree git repo). Covers the unified Provider model, the per-plugin CUE-schema contract (single source → Go params for dev + schema-over-Describe RPC for runtime), the SDK, and the loader.
SKILL.mdUpdated Jun 22, 2026
overthinkos/cue
tools
VerifiedTrustedCommunity
The CUE data-validation / configuration CLI (cue), pinned to v0.16.1. Use when working with the cue candy, installing the cue binary into a box or onto a target:local dev host, or running the offline schema-vendoring pipeline that feeds charly's egress validation.
SKILL.mdUpdated Jun 16, 2026
overthinkos/egress
tools
VerifiedTrustedCommunity
CUE EGRESS validation — validating (and, where it adds value, generating) the config files charly WRITES to a system BEFORE the bytes hit disk. MUST be invoked before working on charly/egress.go, the vendored schemas under candy/plugin-egress/egress-schemas/vendor/, the ValidateEgress / registerVendoredEgressKind path, the offline `task cue:vendor` pipeline, or adding an egress schema for any written artifact (cloud-init, k8s manifests, traefik routes, runtime config, install ledger, systemd/quadlet units, ssh_config, libvirt XML).
SKILL.mdUpdated Jun 16, 2026
overthinkos/check-k8s
tools
VerifiedTrustedCommunity
Kubernetes cluster-probe declarative check verb — the `kube:` check verb (nodes, pods, ingress, storage class, addon health, apply/delete, and arbitrary resource GETs) served out-of-process by the candy/plugin-kube plugin (vendored client-go; no external kubectl required).
SKILL.mdUpdated Jun 14, 2026