mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-11 19:47:12 +03:00
3eb7bd4096
* feat(validation): enforce 60K-char cap on skill reference files Implements issue #277: - validate-references.rb: new oversized_reference_errors check — every references/*.md must be <= 60,000 characters; error reports path, size, and the split-and-reindex remediation; wired into validate-skills.rb - test-validate-skills.rb: 5 fixture tests (under-limit passes, over-limit fails with path+size, exactly-at-limit passes, remediation message, non-.md ignored); the suite now runs in validate.yml after the format check (it was previously untested in CI) - Docs: agent-skills/SKILL.md, agent-skills/references/best-practices.md, and the AGENTS.md Format Compliance table document the cap and the split-and-reindex procedure - Compliance: split remote-systems-administration/references/ansible.md and programming-principles/references/refactoring-guru.full.md into an index + focused parts (content moved verbatim); SKILL.md routing, README, and source-index references updated; pre-existing stale refactoring-guru-smells.md reference repointed to the index - Fix pre-existing quality-gate violations in the programming-principles and remote-systems-administration descriptions (imperative verb + negative boundary) so this PR's CI quality step passes; regenerated llms.txt and marketplace artifacts Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> * test(evals): add eval manifests to modified skills for ratchet The eval-coverage ratchet requires schema-valid eval manifests for any skill modified once coverage is past 50%. This PR modifies programming-principles and remote-systems-administration (splitting their oversized references), so add evals/evals.json to both: - programming-principles: 6 output-quality cases (task-to-book mapping, principled code review, refactor-vs-rewrite, no-op detection, rule distillation, principle conflicts) - remote-systems-administration: 6 output-quality cases (discovery before change, smallest control plane, rollback planning, platform identification, verification evidence, escalation on missing authority) Coverage: 87/145 (60.0%) schema-valid; ratchet clean. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --------- Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
118 lines
9.4 KiB
Markdown
118 lines
9.4 KiB
Markdown
---
|
|
name: remote-systems-administration
|
|
description: >-
|
|
Administer and troubleshoot remote Linux, FreeBSD, NetBSD, OpenBSD, and macOS systems
|
|
safely, one host or a fleet at a time. Use when a task requires SSH, Ansible,
|
|
Paramiko, POSIX diagnostics, service management, software updates, system
|
|
configuration, firewall changes, or evidence-led remote operations. Do not use for
|
|
local-only desktop administration, container or cluster orchestration (route to
|
|
kubernetes), or cloud consoles that expose no remote shell.
|
|
license: MIT
|
|
compatibility: Requires legitimate remote access. Native SSH is the baseline; Ansible or Python with Paramiko is optional for fleet automation.
|
|
---
|
|
|
|
# Remote Systems Administration
|
|
|
|
Use this as an operating decision layer, not a bag of remote commands. Unix-like systems share a vocabulary but not an implementation. Identify the target's platform and active control plane before choosing a command.
|
|
|
|
## Operating contract
|
|
|
|
1. **Discover before changing.** Record target identity, production status, OS and release, service manager, package manager, firewall, access route, privilege path, and current state. Do not infer them from hostname, memory, or inventory labels.
|
|
2. **Use the smallest valid control plane.** Native SSH for a bounded one-host task; Ansible for repeatable desired state across a fleet; Paramiko only when a Python program genuinely needs SSH protocol control that the first two cannot provide.
|
|
3. **Protect access first.** Before changing SSH, routing, DNS, a firewall, privilege escalation, or a network interface, establish a tested rollback and a second recovery path. Keep the current session alive until the new path works.
|
|
4. **Preview, constrain, verify.** Limit the target set; use native validation, dry-run, diff, or a canary when available; then verify the affected service and its user-visible boundary. A zero exit code proves only that command ran.
|
|
5. **Report evidence, not a story.** Preserve bounded per-host results: target, command category, before/after evidence, failures, rollback state, and the remaining uncertainty. Never paste secrets, keys, full configuration files, or unbounded logs into the response.
|
|
|
|
Run the shared classification probe in `references/portable-operations.md`, then load the matching OS/family overlay and run its command preflight. Select a mutation command only after the required preflight and safety gate.
|
|
|
|
## Read-only discovery handoff
|
|
|
|
Use this compact format after a preflight. Fill a field only from observed evidence; otherwise write `unknown` or `not supplied`.
|
|
|
|
- **Target and scope:**
|
|
- **Observed platform and control planes:**
|
|
- **Bounded evidence:**
|
|
- **Unknown or blocked:**
|
|
- **Next safe action:**
|
|
|
|
## First response: classify the job
|
|
|
|
| Situation | Default path | Do not do |
|
|
|---|---|---|
|
|
| Diagnose or make one bounded change on one host | Native `ssh` with a read-only preflight and bounded command/range; do not use a live-follow stream such as `tail -f` | Do not open an interactive shell and make unrecorded edits |
|
|
| Repeat the same desired state across hosts | Ansible inventory + playbook, canary/serial rollout | Do not loop `ssh` blindly across production hosts |
|
|
| Python must coordinate SSH channels, SFTP, or a custom protocol flow | Paramiko with strict host-key verification and explicit timeouts | Do not disable host-key checks or turn a script into ad hoc fleet control |
|
|
| The platform/control plane is unknown | Run bounded discovery from `references/portable-operations.md` | Do not use `systemctl`, `apt`, `pfctl`, or `launchctl` based on a guess |
|
|
| Change affects connectivity, firewall, authentication, reboot, storage, or deletion | Load `references/safety-and-verification.md` first | Do not mutate before a rollback and recovery path are explicit |
|
|
|
|
## Required preflight for every mutation
|
|
|
|
Before the first state-changing command, confirm:
|
|
|
|
- exact host(s), environment, and authorized scope;
|
|
- OS/release and applicable platform overlay;
|
|
- service manager, package manager, firewall implementation, and configuration owner;
|
|
- access identity, elevation method, and whether the connection traverses a bastion;
|
|
- intended state, expected blast radius, rollback command or artifact, and stop condition;
|
|
- validation at both the component layer and the relevant external boundary.
|
|
|
|
> **Connectivity/access pre-execution gate:** explicitly name authorization, retained session, independent recovery path, tested rollback, stop condition, and component plus external-boundary verification. If any is unknown, stop before execution.
|
|
|
|
Read-only discovery may proceed without confirmation. **Read-only means no persistent state:** do not create rollback scripts or captures, stage update metadata, alter files, or call a state-changing operation `preflight`. Stop once the needed platform and control-plane evidence is established. Destructive actions, privilege changes, firewall/remote-access changes, package removals, storage operations, and reboot/shutdown require an explicit directive after this preflight.
|
|
|
|
## Routing references
|
|
|
|
| Need | Load | File |
|
|
|---|---|---|
|
|
| SSH, POSIX diagnostics, bounded output, file transfer, logs, and host discovery | Portable operations | `references/portable-operations.md` |
|
|
| Ansible administration, inventories, roles, collections, secrets, linting, Molecule, rollout, troubleshooting, or platform-specific automation | Ansible administration | `references/ansible.md` (index → `ansible-administration-and-safety.md`, `ansible-runbooks-and-advanced-operations.md`) |
|
|
| Paramiko, or a compact comparison of fleet-control choices and result-accounting requirements | Fleet automation | `references/fleet-automation.md` |
|
|
| Linux classification, init discovery, cross-family safety, or an unknown/minimal derivative | Linux classification | `references/linux.md` |
|
|
| Debian, Ubuntu, or an APT/dpkg host after release and ownership discovery | Debian/Ubuntu overlay | `references/linux-debian-ubuntu.md` |
|
|
| RHEL, Fedora, or a compatible RPM/DNF host after vendor support and lifecycle discovery | RHEL/Fedora overlay | `references/linux-rhel-fedora.md` |
|
|
| SLES, openSUSE, or a zypper/RPM host, including transactional-root discovery | SUSE overlay | `references/linux-suse.md` |
|
|
| Arch Linux or an Arch-derived pacman host after support/repository discovery | Arch overlay | `references/linux-arch.md` |
|
|
| Alpine Linux or an apk/OpenRC host after persistence-mode discovery | Alpine overlay | `references/linux-alpine.md` |
|
|
| FreeBSD rc(8), rc.conf, pkg, jails, and pf/ipfw routing | FreeBSD overlay | `references/freebsd.md` |
|
|
| NetBSD rc.d, rc.conf, service, and pkgsrc routing | NetBSD overlay | `references/netbsd.md` |
|
|
| OpenBSD rcctl, rc.conf.local, pkg_add, syspatch, and pf | OpenBSD overlay | `references/openbsd.md` |
|
|
| launchd, softwareupdate, configuration profiles, pf, and macOS operational limits | macOS overlay | `references/macos.md` |
|
|
| Mutation gates, safety classes, rollback, and verification evidence | Safety and verification | `references/safety-and-verification.md` |
|
|
| Primary documentation and source freshness | Source index | `references/source-index.md` |
|
|
|
|
## Platform boundary
|
|
|
|
Do not flatten platform differences:
|
|
|
|
- `systemctl` is not a BSD or macOS service manager.
|
|
- `rcctl` is OpenBSD-specific; FreeBSD uses rc scripts and `service`.
|
|
- `launchctl` domains and labels are not systemd units.
|
|
- `apt`, `dnf`, `pacman`, `pkg`, `pkg_add`, `softwareupdate`, and `brew` have different update, rollback, and package-origin semantics.
|
|
- Linux nftables, BSD PF, and the macOS Application Firewall are separate control planes. Never translate rules mechanically.
|
|
|
|
## Scope boundaries
|
|
|
|
This skill covers host-level Unix operations. Route containers to `docker-compose`, clusters to `kubernetes`, encrypted tailnet policy to `tailscale`, detection/remediation components to `crowdsec`, and reliability process design to `site-reliability-engineering`.
|
|
|
|
It does not authorize credential recovery, security-boundary bypass, production deletion, provider-console operations, or an unreviewed operating-system upgrade.
|
|
|
|
## Common pitfalls
|
|
|
|
1. **Running the right command on the wrong platform.** Discover the service/package/firewall manager before acting.
|
|
2. **Treating an SSH connection as proof of authority.** Connection success does not confirm sudo policy, host identity, or authorization for the change.
|
|
3. **Using `StrictHostKeyChecking=no` or Paramiko `AutoAddPolicy`.** An unknown host key is an identity event, not a convenience prompt.
|
|
4. **Parallelizing first.** Establish the procedure on one canary, then roll out in bounded batches with a stop condition.
|
|
5. **Calling a service healthy because it started.** Check process/unit state, logs, listening endpoint, and the relevant dependent or external boundary.
|
|
6. **Confusing package upgrades with OS upgrades.** Platform release lifecycle, kernel/base-system updates, and third-party packages have different procedures.
|
|
7. **Repairing a remote host through an access-path change without a rollback.** Preserve a live session and independent recovery channel.
|
|
|
|
## Verification checklist
|
|
|
|
- [ ] Target and platform were discovered from the live host.
|
|
- [ ] Mutation had explicit scope, rollback, and recovery path.
|
|
- [ ] The control plane matched the target platform.
|
|
- [ ] Fleet work used an inventory, bounded concurrency, and a stop condition.
|
|
- [ ] Sensitive values and unbounded output were excluded from evidence.
|
|
- [ ] Verification covered the changed component and its relevant external boundary.
|
|
- [ ] Per-host success, failure, and rollback status are explicit.
|