Skip to content

Add AGENTS.md operating guide and agent skills#1360

Merged
michael-balint merged 1 commit into
masterfrom
dholt/agents-and-skills
Jul 14, 2026
Merged

Add AGENTS.md operating guide and agent skills#1360
michael-balint merged 1 commit into
masterfrom
dholt/agents-and-skills

Conversation

@dholt

@dholt dholt commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add AGENTS.md at the repository root: an operating guide for AI agents (and new humans) with the repository map, first-time setup, Slurm and Kubernetes golden paths anchored on the validation tools from Add machine-readable deployment validation tools #1359, operating rules (validate don't assume, review inventories before running cluster playbooks, reboot awareness, check mode, idempotent reruns), and a list of known behaviors that look like failures but are not (Slurm login GPU hiding, Ansible fact caching, open vs proprietary kernel modules per GPU generation, uninitialized Kubespray submodule).
  • Add skills/ with four self-contained procedures in the cross-tool agent-skills format (SKILL.md with name/description frontmatter): deploy-slurm-cluster, deploy-k8s-gpu-cluster, validate-gpu-cluster, and diagnose-driver-install. Each has preconditions, exact commands, expected outputs, and failure branches drawn from real GPU validation runs.
  • Add a README pointer to AGENTS.md, the validation docs, and skills/.

Validation

  • Doc-only change: git diff --check, YAML frontmatter parse for all four skills, public sanitizer pass on every added file.
  • Inventory group names verified against config.example/inventory (kube_control_plane/etcd/kube_node, slurm-master/slurm-node).
  • Every command in AGENTS.md and the skills was exercised during the Add machine-readable deployment validation tools #1359 live validation cycle on real GPU hardware (full Slurm 26.05.1 and Kubernetes/GPU Operator deployments plus the validation tools).

Notes

  • The gotcha list and skill failure branches encode operational knowledge that previously lived outside the repository; this makes DeepOps operable end-to-end by an agent from a clean checkout.
  • Follow-up candidates for the next train: a skill for airgapped deployments and one for MAAS-based provisioning.

Add an agent-first operating layer so AI agents (and new humans) can
drive DeepOps end to end:

- AGENTS.md: repository map, first-time setup, Slurm and Kubernetes
  golden paths anchored on the validation tools, operating rules
  (validate don't assume, review inventories, reboot awareness, check
  mode, idempotent reruns), and gotchas that look like failures but are
  not (login GPU hiding, fact caching, open vs proprietary kernel
  modules, uninitialized Kubespray submodule)
- skills/: four self-contained procedures with preconditions, exact
  commands, expected outputs, and failure branches drawn from real
  validation runs: deploy-slurm-cluster, deploy-k8s-gpu-cluster,
  validate-gpu-cluster, diagnose-driver-install
- README pointer to AGENTS.md, the validation contract, and skills/
@dholt dholt marked this pull request as ready for review July 14, 2026 15:24
@dholt dholt requested a review from michael-balint July 14, 2026 15:24
@michael-balint michael-balint merged commit 6a64890 into master Jul 14, 2026
31 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants