agentleFS
mountain-beavermountain-beaver/vps-forge/AGENTS.md

vps-forge

AGENTS.md40 starsChanged 3 days agoMITView on GitHub

An Agent Skill for hardening Debian/Ubuntu servers. The repository root is also a Claude Code plugin (.claude-plugin/), and npx skills add / gh skill install find the skill in skills/, so the same tree installs everywhere. The skill lives in skills/vps-forge/: - SKILL.md: workflow and safety rules. Keep it under 500 lines. - references/: one file per phase, loaded on demand. - scripts/: bash that runs as root on servers. - assets/: config templates. Behaviour evals live in evals/ at…

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository3 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Every script passes shellcheck -S warning.

    line 25
  2. Distinctive:

    Keep the skill agent-neutral: say "the agent", not a product name, and do not rely on one tool's built-ins.

    line 43

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

vps-forge

An Agent Skill for hardening Debian/Ubuntu servers. The repository root is also a Claude Code plugin (.claude-plugin/), and npx skills add / gh skill install find the skill in skills/, so the same tree installs everywhere. The skill lives in skills/vps-forge/:

  • SKILL.md: workflow and safety rules. Keep it under 500 lines.
  • references/: one file per phase, loaded on demand.
  • scripts/: bash that runs as root on servers.
  • assets/: config templates.

Behaviour evals live in evals/ at the repository root (claude plugin eval format), outside the skill, so installers that copy the skill folder don't ship them to users.

Commands

  • make test: lint, manifests, version check, audit smoke test, deadman round trip. No sudo needed.
  • make directory: builds dist/directory, the plugin folder that Anthropic's directory reads from the directory branch (only .claude-plugin/plugin.json, the icon, skills/vps-forge, LICENSE and .github/directory/README.md). .github/workflows/directory.yml commits it to that branch on every release tag.
  • make ci: the per-distro CI suites (checks, templates, audit) in podman/docker containers on Debian 12/13 and Ubuntu 22.04/24.04/26.04. make ci-all adds the systemd suites (audit-systemd, deadman-systemd); only CI's macOS job for external-check.sh has no local target.
    • Narrow it with DISTRO=debian:13 make templates or make audit.
  • make lint: the static checks only (no containers, no network, no root).
  • Tools: bash, shellcheck, python3 with PyYAML, jq, zip, and podman or docker for the container suites.
  • make eval: runs the behaviour evals. It spends tokens, so run it only when asked.

Invariants (CI enforces most of them)

  • audit.sh is read-only. tests/audit-scenarios.sh checksums the filesystem around it.
  • external-check.sh runs on users' Macs, so it must stay compatible with bash 3.2: no mapfile, no ${var,,}, no associative arrays.
  • Every script passes shellcheck -S warning.
  • Versions must agree in four places: .claude-plugin/plugin.json, the first released ## x.y.z heading in CHANGELOG.md, VERSION= in audit.sh, and metadata.version in the SKILL.md frontmatter (installers that copy only the skill folder keep it).
    • Release: bump all four, then tag vX.Y.Z. The release workflow refuses a tag that doesn't match.
  • Templates use <placeholder> syntax.
    • A new placeholder needs a value in fill() in tests/lib.sh, otherwise tests/templates.sh fails.
    • The write_files in assets/cloud-init.yaml must stay consistent with the standalone templates. The test compares the effective sshd values.
  • Any SSH, firewall, sudo or PAM guidance keeps the dead-man flow: arm → change → validate → test from a new session → disarm.

Tests that modify /etc

tests/templates.sh and tests/audit-scenarios.sh rewrite /etc and refuse to run outside a container. Always start them through tests/in-container.sh, never on the host.

README translations

README.zh-CN.md, README.ja.md and README.ru.md mirror README.md; tests/translations.py (part of make test) fails when their links, images, commands, tables or <details> blocks differ, and warns when README.md changed since the sha256 in their header comment. When you change README.md, change the translations the same way and update that hash (sha256sum README.md | cut -c1-12). Only the README is translated: the skill itself stays in English.

Skill text

  • Keep the skill agent-neutral: say "the agent", not a product name, and do not rely on one tool's built-ins.
  • name must stay vps-forge (it equals the directory name); description stays under 1024 characters and leads with what the skill does and when to use it.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.