linux-skills Agent Guide

Codex-only model setup and Kaizen review

Apply this section only when the active runner is Codex. Claude and other runners must skip it and retain their own models and full engine capabilities.

Before substantive Codex work, resolve this engine's directory and an available Python 3.11+ interpreter (use its absolute path if absent from PATH), then run python <engine-root>/.codex/ensure_model_policy.py --runtime codex --check. If it reports configuration drift, Peter authorises the bounded --runtime codex --apply repair, followed by --check. The helper backs up changes and preserves unrelated settings. If Python or configuration access is unavailable, report the limitation; do not replace the user's config wholesale. Read .codex/model-policy.md for the full contract. Use Luna (gpt-6-luna) with high reasoning by default for orchestration, research, audit, review, and implementation. Use Astra (gpt-6-astra) only when Peter explicitly selects it for the task; never select or fall back to GPT-5.6. Report unavailable required GPT-6 models. A running session may need restarting for root settings to apply.

Every Kaizen cycle MUST check latest official model releases and actual runtime availability, record dated evidence and a retain/change decision, and evaluate better candidates before recommending replacement. Preserve the pins until Peter authorises a verified change. Missing model-currentness evidence is NOT_ASSESSED. This Codex adapter must not change CLAUDE.md, Claude configuration, domain doctrine, permission settings or skill access.

Universal agent integration

See .skills-engine/engine-manifest.yaml for the declarative contract used by the optional universal coordination package. The router and domain SKILL.md files remain authoritative.

The package may read the router, discover skills, inspect Git, and run only declared checks. Missing evidence is NOT ASSESSED; writes, pulls, publication, submissions, ledger/filing changes, deployment, or control changes require explicit approval.

Project context: if the working project root holds a PROJECT.md with project_schema: 1, read it before planning. It points to this engine's own context sources and never replaces them.

Rules

Always-on cross-cutting principles live in rules/ — see rules/README.md. Load rules/common/core.md alongside the routed skill for any non-trivial task; it is short and does not replace the skill, only sets the baseline the skill operates within.

Mandatory Digital Research currentness gate for Kaizen

Every Kaizen audit, skill edit, reference update, validator change, and standardisation decision MUST begin with the Digital Research Engine at digital-research-engine (resolve through the device catalogue). Read its source-evaluation and source-verification skills and the currentness gate reference docs/continuous-improvement/kaizen-currentness-gate.md.

Before admitting any standard, policy, law, technology, platform capability, software version, command, security control, benchmark, or lifecycle claim, record source scope, publication/version date, access date, freshness class, review date, support status, and uncertainty. Use current authoritative primary sources; quarantine stale/ambiguous/unsupported claims and mark them NOT_ASSESSED. Books are durable concept inputs only.

The shared control plane is adapted to operational safety in docs/control-plane-adoption.md; the central registry is chwezi-dev-engine/docs/engine-control-plane.json (resolve through the device catalogue).

Purpose

This repository is a Linux server management skills system centred on portable SKILL.md files. The canonical operating content is runner-neutral and can be loaded by Claude Code, Codex, or another agent runner without duplicating logic or requiring a particular directory layout.

This repository contains Linux skills, commands, tips, and notes.

The repository contains:

• 44 specialist skills grouped into 16 numbered category directories (01-provisioning-and-bootstrap through 16-network-equipment), e.g. 04-web-and-mail-services/linux-webstack/, 07-security-and-hardening/linux-security-analysis/, 12-containers-and-orchestration/linux-container-engine/, 15-compliance-and-auditing/linux-auditd-rules/, and 16-network-equipment/cisco-ios-patterns/ (the linux-sysadmin/ hub stays at the repo root). 16-network-equipment/ skills are network-appliance skills, not linux-*-named, and are exempt from the two-family Distro support invariant (see that category's own SKILL.md rationale).
• A colocated SKILL.md in each skill directory
• Optional references/ and scripts/ folders inside each skill directory
• Repo-wide engine and operational docs under docs/
• Shared executable tooling under scripts/

Do not assume the repo must live under a particular folder name. A runner may use any configured skill root or the repository in place. Claude Code commonly uses ~/.claude/skills, but that is an optional adapter path; Codex and generic agents should treat the existing skill directories as the source of truth without requiring that path.

Portable entry points

• Generic or manual use: resolve the repository root from this file or README.md, then load linux-sysadmin/SKILL.md as the default route.
• Codex or another agent runner: load AGENTS.md and the selected SKILL.md directly. No runner-specific setup script or fixed home-directory path is required.
• Claude Code: CLAUDE.md and scripts/setup-claude-code.sh are optional Claude-specific overlays/bootstrap. They must not be treated as prerequisites for the canonical skills. The bootstrap requires an explicit --dry-run review, exact target flags, separate network/user/ privileged-write authority, and a recovery-file path before a real mutation is allowed. Before a real run, review its --dry-run plan and supply exact targets, action choices, authority flags, and a new recovery-file path. It never pulls an existing checkout or executes a downloaded shell script.

Two-Family Support (Debian/Ubuntu + RHEL)

Every specialist skill and sk-* script supports both the Debian family (Debian, Ubuntu) and the RHEL family (Fedora, RHEL, CentOS Stream, Rocky, Alma, Oracle). When acting on a task:

• Read the skill's ## Distro support matrix (its first H2) to pick the right command/path/service for the target distro.
• In scripts, never hardcode apt/ufw/apache2. Use the common.sh primitives: detect_distro, pkg_install, pkg_is_installed, ensure_epel, svc_name, firewall_allow, web_conf_dir, web_reload, require_family.
• Deep-dive RHEL references: firewalld, SELinux, httpd/conf.d, NetworkManager/nmcli, Kickstart — each lives under its owning skill's references/.
• Design, phasing, and status: docs/multi-distro/plan.md. The invariant scripts/tests/check-distro-matrix.sh must pass.
• require_family takes <debian|rhel|any>.
• The big family differences are SELinux (vs AppArmor), firewalld (vs UFW), httpd+conf.d (vs apache2+sites-available), NetworkManager (vs Netplan), dnf-automatic (vs unattended-upgrades), wheel (vs sudo), and Kickstart (vs autoinstall).
• scripts/tests/check-distro-matrix.sh asserts every specialist skill carries a Distro support matrix — run it after adding/editing a skill.

Repository structure

• linux-sysadmin/ - Hub skill: routes to all specialist skills (start here)
• NN-category/linux-*/ - Specialist skills grouped into 15 numbered categories: 01-provisioning-and-bootstrap, 02-users-access-and-secrets, 03-networking-and-dns, 04-web-and-mail-services, 05-services-and-virtualization, 06-storage-and-filesystems, 07-security-and-hardening, 08-observability-and-logging, 09-troubleshooting-and-recovery, 10-automation-and-scripting, 11-databases-and-caching, 12-containers-and-orchestration, 13-backup-and-archiving, 14-performance-and-kernel, 15-compliance-and-auditing
• 16-network-equipment/ - Network appliance skills (Cisco IOS/IOS-XE, Netmiko SSH automation, pre-deployment config validation), added 2026-09-20. These are not linux-*-named and are deliberately exempt from the two-family Distro support invariant above — they target vendor router/switch operating systems, not a Linux distribution. See 16-network-equipment/*/SKILL.md for each skill's own "Distro support: Not applicable" rationale.
• meta/ - Engine-authoring skills (skill-writing, skill-safety-audit)
• commands/ - Useful command references organized by topic
• scripts/ - Reusable shell scripts and snippets
• notes/ - General Linux notes and troubleshooting guides

Engine design

• All conventions live in docs/engine-design/spec.md.
• Skill authoring and July 2026 release gates live in docs/engine-design/skill-authoring-standard.md.
• The zero-debt gates are python3 -X utf8 scripts/validate_skills.py --baseline quality-baseline.json and python3 -X utf8 scripts/routing_smoke_test.py; run both after changing a skill contract or route. The README's Validation section lists every registered check with its exact command, dependencies (PyYAML, pytest) and what runs only in CI, in a container or as root.
• The planned script catalogue (88 scripts) is in docs/engine-design/script-inventory.md. The shipped scripts are the 26 sk-* sources found by find . -name 'sk-*' -type f, 13 of them tier 1.
• Scripts install to /usr/local/bin/ with the sk- prefix via install-skills-bin.
• Hybrid install: sudo install-skills-bin core at setup, per-skill lazy install on first use. The installer needs root even with --dry-run; install-skills-bin --list does not. Installed copies do not follow the checkout: after an update, compare and reinstall as in the README's Updating installed scripts.
• Every script sources /usr/local/lib/linux-skills/common.sh.

Current Kaizen evidence

The 2026-10-29 audit records this cycle's user-requested 45/100 initial cap and 95/100 target. Preserve raw scores and explicit unassessed checks; never promote a target to an achieved score. Use the security triage runbook for current advisory matching and the dated source register for its limitations. The portfolio refresh records native plugin discovery and the hard file-cap regression. The 2026-10-31 pass 2 continues that cycle: it fixed the SSH drop-in naming, sk-pg-backup file modes, configuration trust and the audit-log fallback, and its operator note lists the host checks that follow. The Linux lab wave of the same day ran rootless Podman labs on Debian 12, Fedora 44 and MySQL 8.4; its operator note lists the host checks it adds. Its published score is raw 77.9 and min(raw, 65) = 65.0; the 95 target is not met. Ubuntu, enterprise RHEL, Debian 13 and real cloud-init images are NOT_ASSESSED. Installed sk-* copies and /usr/local/lib/linux-skills/common.sh can be older than this checkout; compare before relying on them. The docs index lists every record folder. The historical 88-script inventory is a roadmap; installed availability comes from scripts/install-skills-bin --list and current skill manifests.

Baseline Skills

Kaizen is mandatory for the engine and every operational product. Load meta/kaizen-improvement-system/SKILL.md for audits and improvement planning; cap published audits at 65/100 and target 95/100 with dual-distro, safety, rollback, recovery, and reviewer evidence.

Start from these skills unless the task is already narrowly scoped:

• linux-sysadmin: routing hub for Linux server tasks
• linux-bash-scripting: mandatory meta-skill before writing or reviewing sk-* scripts
• skill-writing: meta-skill for creating or upgrading portable skills
• skill-safety-audit: review gate for new or imported skill content

For current or uncertain distro, security, compliance, vendor, platform, legal, or safety claims, route to the Digital Research Engine (GitHub repository chwezi-research-engine, catalogue id digital-research-skills; resolve its checkout through the active engine-routing table or the catalogue) and load its source-evaluation and source-verification skills before standardising a command or policy. This Linux engine is an operational consumer of that research engine, not a substitute for current-source verification.

Routing

Use linux-sysadmin as the default entry point for server work, then route quickly:

• Provisioning and bootstrap: linux-server-provisioning, linux-cloud-init, linux-package-management, linux-config-management
• Deployment and web stack: linux-site-deployment, linux-webstack, linux-mail-server, linux-service-management
• Security: linux-security-analysis, linux-server-hardening, linux-access-control, linux-firewall-ssl, linux-intrusion-detection, linux-ngo-cyber-resilience, linux-secrets
• Operations: linux-system-monitoring, linux-log-management, linux-observability, linux-disk-storage
• Networking: linux-network-admin, linux-dns-server
• Virtualization and automation: linux-virtualization, linux-repo-sync
• Databases and caching: linux-mysql-mariadb, linux-postgresql, linux-inmemory-stores
• Containers and orchestration: linux-container-engine, linux-container-deployment, linux-image-hygiene
• Backup and archiving: linux-rsync-sync, linux-archive-integrity, linux-filesystem-snapshots
• Performance and kernel: linux-sysctl-tuning, linux-kernel-modules, linux-perf-profiling
• Compliance and auditing: linux-auditd-rules, linux-file-integrity, linux-benchmark-scanning
• Incident and recovery: linux-troubleshooting, linux-disaster-recovery

Windows hosts: windows-admin-engine-skills (windows-admin-engine-skills; resolve through the device catalogue) — the reciprocal statement on that engine's side is "Linux hosts: linux-skills" (in that engine's AGENTS.md). The two engines are the estate's paired infrastructure engines; route to whichever OS the target host actually runs.

When the task is about creating or upgrading skills in this repo, use skill-writing. When the task is about script authoring or review under scripts/, use linux-bash-scripting first.

Skill authoring and release follow docs/engine-design/skill-authoring-standard.md. Start new skills from templates/skill-template.md, add routing fixtures, and run the zero-debt validator, routing smoke test, canonical quick validator, canonical engine scanner, distro-matrix test, safety review, and anti-slop release gate. Never add findings to quality-baseline.json; it is a zero-debt assertion, not a waiver.

How To Use Skills In This Repo

1. Read the target skill's SKILL.md first.
2. Treat the top contract sections as the portable execution layer: Use when, Do not use when, Required inputs, Workflow, Quality standards, Anti-patterns, Outputs, and References.
3. Use the rest of the skill body as the detailed manual procedure.
4. Load references/ files only when the active task needs the extra depth.
5. Treat scripts/ and listed sk-* tools as optional accelerators unless the task is explicitly about script development.

Working Rules

• Preserve existing Claude Code behavior. Do not move skill directories or split logic into a new skills/ tree unless there is no viable alternative.
• Keep SKILL.md concise and execution-oriented. Move heavy material into references/.
• Do not assume optional scripts are installed. Manual commands remain the baseline truth.
• Prefer local repository references over invented guidance. If a skill points to docs/ or references/, follow those files.
• Keep repo-level policy in AGENTS.md and Claude-specific policy in CLAUDE.md; do not bury repo policy inside unrelated skills.
• If a skill changes in a way that affects sk-* scripts or manifests, update the related script docs and manifests in the same change.
• Keep platform evidence in docs/continuous-improvement/platform-test-matrix-2026-08.md; a local structural or fixture result must not be reported as live Linux or production evidence.
• Two-family by default. Every new or edited specialist skill MUST carry a ## Distro support matrix (Debian/Ubuntu ↔ RHEL family) as its first H2, and every sk-* script MUST use the common.sh distro primitives instead of hardcoding a package manager / firewall / web server. Run scripts/tests/check-distro-matrix.sh to verify.
• Author attribution is mandatory. Every SKILL.md, script, and generated document must credit Peter Bamuhigire (techguypeter.com, +256784464178) — in SKILL.md frontmatter metadata.author, in script #: Author: headers, and in doc footers.
• Scripts track skills automatically. When a skill's knowledge changes (new Ubuntu version, better approach, updated standard), proactively update every affected script in the same session — do not wait to be told.
• New repo on server? It MUST be added to both /usr/local/bin/update-all-repos and /usr/local/bin/update-repos. See notes/new-repo-checklist.md for instructions.
• First use of a skill on a new server? Run sudo install-skills-bin <skill-name> to install that skill's scripts into /usr/local/bin/. For initial server setup, run sudo install-skills-bin core to install the tier-1 foundation scripts.
• Scripts the user must run use the shortest possible path. One line: a bare sk-* name on PATH, or ~/<name>.sh for a one-off. Never a skill-directory, scratch, or temp path, and no required output-path argument. See rules/common/core.md and linux-bash-scripting ("Handing a script to a user").

Never store book extractions

Book extractions, book summaries and chapter-by-chapter notes must never be stored in this repository (no book-extractions/, extracted-books/ or book-study/ folder, no *-extraction.md book digests). Knowledge from books enters only as paraphrased, task-oriented skill content and references/ files (procedures, checklists, decision rules) with a short citation (Author (Year) Title, Publisher). Verbatim quotations stay rare and under 25 words. The portfolio check chwezi-engine-agents/scripts/validate-no-book-extractions.py fails if an extraction folder appears.

Quality Expectations

Machine-error editorial gate (ME1-ME7)

Apply Digital Research's docs/continuous-improvement/machine-errors-editorial-gate-2026-09-03.md to runbooks, incident explanations, change plans, and operator-facing notes. Check ME1 semantic repetition, ME2 decorative symmetry, ME3 over-explanation, ME4 inflated risk or benefit, ME5 generic examples, ME6 repeated rhetorical tics, and ME7 paragraphs with no command, condition, evidence, decision, or recovery step. Preserve repeated commands, warnings, rollback steps, and safety gates when they are functionally required; record the exception. Unavailable host, lab, or source evidence is NOT_ASSESSED.

Impeccable-derived AS overlay

When a runbook, dashboard, presentation, or web handoff contains visual or human-facing output, apply AS1-AS7 from Digital Research. Purple gradients, glassmorphism, neon glow, AI-beige defaults, decorative editorial scaffolding, and decorative motion are no-ship choices. For text-only operations, use AS1, AS3, AS5, and AS6; mark visual checks not_applicable. Preserve repeated commands, warnings, rollback steps, and safety gates because they carry operational function. Unavailable host, render, browser, or detector evidence remains NOT_ASSESSED. AS1-AS7 coverage is explicit: AS2, AS4, and AS7 are not_applicable for text-only runbooks, while visual or rendered operational artefacts require the full overlay.

• Skills must be composable: one clear responsibility per skill, with explicit handoffs.
• Outputs must be actionable: findings, commands, decisions, verification steps, or produced artifacts.
• References must be curated, structured, and directly useful. Avoid raw dumps.
• Platform-specific behavior should be optional layering, not the only way a skill works.
• Safety-sensitive operations must remain explicit about confirmation, validation, and verification.

Codex Notes

Codex can use this repository effectively without a special folder structure if:

• SKILL.md stays portable and self-explanatory
• task-to-skill routing is clear from this file and linux-sysadmin
• references are local and explicit
• Claude-specific assumptions are presented as examples, not universal requirements

When updating the repo for compatibility, prefer minimal layering over restructuring.

Design / typography / UI/UX (cross-cutting — consult IN ADDITION)

Any work touching how an artifact LOOKS — font/typeface choice, type scale, colour, layout/grid, visual identity, web/desktop/mobile UI screens, or the visual formatting of a DOCX/PPTX/PDF/XLSX — routes to the chwezi-design-engine engine, the single home for ALL design/UI/UX skills and the anti-AI-slop doctrine.

Resolve its location on THIS device from the active runner's global engine-routing table or AGENTS.md — never assume an absolute path; it varies per machine. Then read its README.md → doctrine/design-doctrine.md → glob skills/**/SKILL.md fresh and route by frontmatter (read SKILL.md directly, not via the Skill tool). Content and structure stay in THIS engine; presentation comes from chwezi-design-engine. Hard rule: never use a banned AI-slop font as primary type — hard ban: Inter, Geist, Roboto, Open Sans, Lato, Arial, Fraunces, IBM Plex (all faces); secondary ban: Space Grotesk, Instrument Serif, Instrument Sans, Poppins, Montserrat, Nunito, Nunito Sans, Newsreader, Cormorant (all cuts), Crimson Pro, Plus Jakarta Sans, DM Sans, Outfit, Playfair Display, Lora, Space Mono; Roboto Mono and IBM Plex Mono are banned as monospace choices; Source Sans 3 only as a paired body face; no bare system stacks alone. State the chosen typeface and reason before producing any artifact.

DOMAIN PROMPT GENERATION CONTRACT

For a prompt handoff, read the local domain prompt contract. Generate a ready-to-paste operational prompt with exact target, current state, one operation, commands/checks, risk class, approval boundary, maintenance window, rollback, and evidence. Never guess hosts, credentials, versions, or live state. Ready-to-paste prompt: include assumptions and NOT ASSESSED gaps. Failure action: stop on target or evidence failure, or revise one reversible step.

PORTFOLIO CRAFT CONTRACT

Load chwezi-engine-agents/docs/operations/portfolio-craft-standard-2026-09-04.md (resolve through the device catalogue) when available. Execute administration work in bounded changes: frame the target and recovery consequence, select one operation, inspect ownership and current state, preview or stage the smallest change, verify normal and failure behaviour, refine the runbook or script, and record before/after and rollback proof. Do not generate a complete server change as one opaque batch. Apply Observe -> Baseline -> Select -> Experiment -> Check -> Standardise -> Teach -> Re-measure to kaizen itself. Missing host, lab, source, live, or recovery evidence is NOT ASSESSED, never a pass.