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.
- .claude/CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- vps-forgeSkill
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
- Very specific: line 25
Every script passes shellcheck -S warning.
- Distinctive: line 43
Keep the skill agent-neutral: say "the agent", not a product name, and do not rely on one tool's built-ins.
≈ “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.
Files
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: buildsdist/directory, the plugin folder that Anthropic's directory reads from thedirectorybranch (only.claude-plugin/plugin.json, the icon,skills/vps-forge, LICENSE and.github/directory/README.md)..github/workflows/directory.ymlcommits 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-alladds the systemd suites (audit-systemd,deadman-systemd); only CI's macOS job forexternal-check.shhas no local target.- Narrow it with
DISTRO=debian:13 make templatesormake audit.
- Narrow it with
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.shis read-only.tests/audit-scenarios.shchecksums the filesystem around it.external-check.shruns on users' Macs, so it must stay compatible with bash 3.2: nomapfile, 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.zheading inCHANGELOG.md,VERSION=inaudit.sh, andmetadata.versionin theSKILL.mdfrontmatter (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.
- Release: bump all four, then tag
- Templates use
<placeholder>syntax.- A new placeholder needs a value in
fill()intests/lib.sh, otherwisetests/templates.shfails. - The
write_filesinassets/cloud-init.yamlmust stay consistent with the standalone templates. The test compares the effective sshd values.
- A new placeholder needs a value in
- 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.
namemust stayvps-forge(it equals the directory name);descriptionstays under 1024 characters and leads with what the skill does and when to use it.
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
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.

