DebianClub AI Skills

DebianClub AI Skills are reliability rules for AI coding assistants and terminal agents working on Debian/Linux systems. They do not replace documentation. They force the agent to identify the environment, verify package names, inspect logs, and review command risk before giving advice.

The first skill in this repository is skills/debian-linux-reliability/. It uses one main skill with multiple focused submodules.

Why This Exists

AI mistakes on Linux often come from:

• Applying Ubuntu, Arch, or macOS commands to Debian
• Inventing package names
• Ignoring stable, backports, testing, and unstable differences
• Guessing service failures without checking systemctl and journalctl
• Recommending risky commands such as curl | sh, rm -rf, or chmod -R
• Missing WSL, containers, non-systemd environments, or non-amd64 architectures

DebianClub AI Skills make the agent collect facts first.

Current Skill

Submodules

debian-linux-reliability includes these modules:

Safety Policy

The first version defaults to no automatic system modifications. Scripts only collect information. They do not install packages, delete files, edit configuration, or restart services.

If the user wants the AI to perform a change, the agent must first explain:

• Which files, packages, services, or network rules are affected
• Why the change is needed
• How to inspect before changing
• How to verify after changing
• How to roll back if it fails

DebianClub Documentation Binding

The skill prefers DebianClub repository content for explanations, including:

• APT Package Management
• Debian Backports
• deb822 Sources
• Network Configuration
• NVIDIA Optimus
• Podman
• System Security

Live state must still come from the user's machine. Documentation explains. Read-only probes verify current facts.

Usage

In an AI agent that supports skills, invoke:

Use $debian-linux-reliability to diagnose this Debian package installation issue.

Repository files:

skills/debian-linux-reliability/SKILL.md
skills/debian-linux-reliability/references/
skills/debian-linux-reliability/scripts/

Local Install

The repository includes a user-local installer. By default, it installs to ${CODEX_HOME:-$HOME/.codex}/skills. It does not use sudo and does not overwrite an existing install unless --replace is passed.

bash skills/scripts/install-skill.sh debian-linux-reliability

If the target already contains a skill with the same name, inspect it first. Replace it only when intended:

bash skills/scripts/install-skill.sh --replace debian-linux-reliability

Platforms or CLIs can read the distribution index:

skills/registry.json
/skills.json

Release And Evaluation

Build a versioned skill package:

bash skills/scripts/package-skill.sh debian-linux-reliability

The script writes a .tgz archive and a manifest with version, size, and SHA-256. The default output directory is skills/dist/, which is not tracked in git.

Publish to a remote GitHub Release:

bash skills/scripts/publish-skill-release.sh --dry-run debian-linux-reliability
version="$(jq -r '.skills[] | select(.name == "debian-linux-reliability") | .version' skills/registry.json)"
git tag "skills/debian-linux-reliability/v${version}"
git push origin "skills/debian-linux-reliability/v${version}"

--dry-run only builds artifacts and prints the release command. After the tag is pushed, .github/workflows/skills-release.yml validates, packages, and uploads the .tgz archive and manifest.

Generate a score report from real agent responses:

bash skills/scripts/score-evaluation.sh --responses path/to/responses --output report.md

The report includes four grades: excellent, pass, risky, and fail. For failure fixtures or regression samples that cover only selected prompts, use:

bash skills/scripts/score-evaluation.sh --responses path/to/responses --present-only

For a new prompt set captured from real usage, pass a custom prompt file:

bash skills/scripts/score-evaluation.sh --prompts path/to/prompts.md --responses path/to/responses

Long-term maintenance flow:

• Redact real prompts and responses first, removing hostnames, usernames, IP addresses, tokens, private keys, and customer identifiers
• Add new prompts to tests/field-regression-prompts.md, or create a topic-specific prompt file
• Place matching agent responses in a dedicated responses directory
• Register the prompt file, responses directory, expected grade, and sample count in tests/regression-cases.tsv
• Run bash skills/scripts/validate-all.sh to verify registered prompt numbering, coverage rows, module names, and positive, negative, edge, and field regression samples

Maintenance Resources

The skill currently includes:

• Multilingual notes: Simplified Chinese, Traditional Chinese, Japanese, and Korean
• Realistic troubleshooting examples: tests/evaluation-prompts.md covers APT, systemd, networking, GPU, containers, development setup, Debian packaging, and security audit scenarios
• Baseline agent responses: tests/fixtures/evaluation-responses/ contains 30 scoreable samples
• Failure response samples: tests/fixtures/failure-responses/ covers dangerous commands, cross-distribution repositories, and unapproved mutation advice
• Edge-context samples: tests/fixtures/edge-responses/ covers safe warnings and unsafe recommendations that contain safety words
• Field regression seeds: tests/field-regression-prompts.md and tests/fixtures/field-regression-responses/ provide the long-term intake format
• Regression case manifest: tests/regression-cases.tsv keeps the positive baseline and negative samples in continuous validation
• Automated validation: skills/scripts/validate-all.sh checks skill metadata, the distribution registry, shell syntax, risk checks, redaction rules, and troubleshooting prompt coverage
• Local distribution entry points: skills/registry.json and skills/scripts/install-skill.sh
• Versioned releases: skills/scripts/package-skill.sh
• Remote releases: skills/scripts/publish-skill-release.sh and .github/workflows/skills-release.yml
• Tiered agent score reports: skills/scripts/score-evaluation.sh

Roadmap

Next steps include adding more regression samples from real usage.