Agent Skill for DevOps: Runbooks, Deployments, and Incident Workflows

An agent skill for DevOps is a reusable operational runbook for an AI agent. It tells the agent how to perform a bounded operations job: release readiness, CI failure triage, post-deploy canary checks, Terraform plan review, Kubernetes rollout inspection, incident timeline reconstruction, or rollback preparation.

It should not be a vague instruction to "fix production." DevOps skills need stricter boundaries than most agent skills because they sit near production systems, credentials, customer data, infrastructure state, and incident response. A useful skill turns an existing operational procedure into an inspectable package. It does not turn an agent into an unbounded production operator.

OpenAI's Codex skill docs define a skill as a directory with SKILL.md plus optional scripts/, references/, and assets/ (OpenAI Codex skills). That package model fits DevOps because real runbooks are not just prose. They need environment names, safe commands, dashboard links, service ownership, alert context, escalation rules, and stop conditions.

If you are still deciding where a skill fits in the stack, start with Agent Skill vs Tool: What Is the Difference?. The short version is: tools give the agent access, while skills give the agent a procedure for using that access responsibly.

The most important design choice is whether the skill is allowed to act or only investigate.

Skill type	Allowed behavior	Example output
Read-only triage	inspect logs, metrics, configs, recent deploys	likely cause, evidence, next command
Deploy checklist	verify preconditions and post-deploy signals	pass/fail checklist
Rollback preparation	gather steps and blast radius	rollback plan for human approval
Infra review	inspect Terraform, CI, or config diffs	risk list and validation commands
Incident report	summarize timeline after resolution	timeline, impact, follow-ups

For many teams, the first useful version should be read-only. Let the skill collect evidence and prepare recommendations before allowing it to run mutating commands. This is especially true when the agent can reach GitHub Actions, cloud consoles, Kubernetes clusters, Terraform state, PagerDuty, Slack, Datadog, Honeycomb, or production logs.

MCP's tools specification says applications should keep a human in the loop for tool invocations and present confirmation prompts for operations (MCP tools specification). A DevOps skill should treat that as a design constraint. The skill can say, "prepare a rollback command," but the host, tool layer, or human reviewer should still control whether the command runs.

Define:

• Environment: local, staging, production, or sandbox.
• Permissions: read-only, approval-required, or explicitly allowed actions.
• Trusted sources: logs, dashboards, deploy history, status page, runbooks, and alerts.
• Dangerous operations: restarts, deletes, migrations, rollbacks, credential access.
• Evidence: timestamps, command outputs, metric windows, and affected services.
• Escalation: when to stop and page a human.

The contract should be visible near the top of SKILL.md, not buried inside a paragraph. DevOps work fails when the agent has to infer whether "deploy" means staging or production, whether it can use kubectl, whether terraform apply is forbidden, or whether a failed smoke test should trigger rollback preparation.

---
name: post-deploy-canary
description: Verify a deployment using read-only health checks, logs, and key metrics. Use after a deploy to staging or production. Do not mutate infrastructure.
---

Confirm service, environment, version, and deploy time.
Inspect:
1. deployment status
2. health checks
3. error rate
4. latency
5. relevant business or product metric
6. recent logs for new error signatures

Return pass/fail, evidence links or command outputs, and recommended next action.
Stop before rollback, restart, migration, or config mutation unless explicitly approved.

This is a practical DevOps skill because it gives the agent a limited role. It can accelerate verification without silently taking control of production.

GitHub Actions environments are a good match for this pattern because they can hold environment secrets and deployment protection rules (GitHub Actions environments). A canary skill should not replace those gates. It should inspect them: which environment was targeted, which reviewers approved, which deployment job ran, which SHA shipped, and which signals changed after the deploy.

A release-readiness skill should answer one question: "Is this change ready to enter the next deployment gate?"

For a GitHub Actions repository, that skill might require the agent to:

1. Identify the pull request, branch, target environment, and commit SHA.
2. Read the workflow run status and failing jobs before summarizing.
3. Check whether the job uses a protected GitHub environment for staging or production.
4. Confirm required reviewers, wait timers, or custom deployment protection rules when they apply.
5. Inspect changed files for migrations, infrastructure, secrets, feature flags, and operational docs.
6. Return a go/no-go table with blocking findings first.
7. Stop before approving, rerunning, canceling, or deploying unless the user explicitly asks.

GitHub's deployment review flow is useful because an environment can pause deployment until a reviewer approves or rejects it (GitHub reviewing deployments). Custom deployment protection rules go further by letting a GitHub App consult third-party systems before a deployment proceeds (GitHub custom deployment protection rules). An agent skill should cooperate with those controls, not recreate them in prose.

The tradeoff is speed versus authority. A release-readiness skill can make the reviewer faster by collecting CI status, diff risk, and deploy metadata. It should not become a second, informal approval system that bypasses GitHub's protected environment.

Terraform is where the skill-versus-script boundary matters. HashiCorp's terraform plan command creates an execution plan to preview infrastructure changes (Terraform plan). terraform apply can then carry out a saved plan file, and saved-plan mode applies the operations in that file without asking for confirmation (Terraform apply).

That makes a good first Terraform skill a plan reviewer, not an apply bot.

Example contract:

Read Terraform changes only in the requested workspace.
Run formatting, validation, and plan commands if the repo supports them.
Summarize creates, updates, deletes, replacements, IAM changes, network exposure, data retention changes, and cost-sensitive resources.
Flag any drift, backend ambiguity, missing workspace, missing var file, or provider authentication issue.
Do not run terraform apply, destroy, state rm, state mv, import, taint, or force-unlock.

Community discussions around Terraform in CI tend to orbit the same concern: "How do we ensure CI does not do something horrific in production?" (r/devops discussion on safe Terraform apply in CI). That is exactly the right fear to encode into a skill. The skill should force the agent to say what will change, what might be destructive, which account or workspace it saw, and where human approval is required.

If the skill includes a helper script, have the script read Terraform's machine-readable plan JSON instead of scraping terminal prose; HashiCorp documents that Terraform can output a JSON representation of plan changes for tooling (Terraform JSON output format). If the team already uses HCP Terraform policy enforcement with Sentinel or OPA, the skill should report the policy results and explain blockers, not duplicate the policy engine in instructions (HCP Terraform policy enforcement).

If your team already uses Terraform Cloud, Atlantis, Spacelift, env0, or GitHub Actions with required reviewers, the skill should describe how to inspect that system's output. Do not ask the agent to invent an IaC deployment platform inside SKILL.md. For a deeper split between instructions and deterministic code, see Agent Skill vs Code: What Should Live in Instructions?.

Kubernetes skills should be even more conservative because cluster commands can change live traffic quickly. The official Kubernetes Deployment docs show kubectl rollout status as the normal way to check whether a Deployment completed (Kubernetes Deployments). Kubernetes also documents kubectl rollout undo for rolling back deployments, daemonsets, and statefulsets (kubectl rollout undo).

That does not mean the agent should run rollback automatically. Rollback may restore an image, but it may not reverse a database migration, feature flag change, queue schema change, or external dependency rollout. A Kubernetes rollback-prep skill should gather:

• namespace, context, deployment name, and current revision
• image tags and previous successful revision
• rollout status and event history
• pod readiness, restarts, probes, and recent logs
• linked release, migration, and feature-flag changes
• blast radius and customer impact evidence
• the exact rollback command, marked as approval-required

Reddit discussions about CI/CD rollback often emphasize returning to a known-good artifact and keeping migrations forward and backward compatible for at least one release (r/devops rollback discussion). Separate database-migration threads repeat the same practical theme: backward-compatible schema changes keep rollback possible when code and data evolve at different speeds (r/devops database rollback discussion). That is a strong rule to put directly into the skill. The agent should not say "rollback is safe" unless it has checked the artifact, the migration story, and the current traffic path.

Google's SRE incident management guide frames incident response as a process for minimizing impact, coordinating mitigation, and learning afterward (Google SRE incident management guide). The Google SRE workbook chapter on incident response gives concrete incident-management patterns and examples from Google and PagerDuty (Google SRE workbook: incident response).

An incident skill should not be "RCA everything." During an active incident, the useful jobs are narrower:

• collect alert, deploy, flag, and error-budget context
• identify the likely changed systems
• maintain a timeline from alerts, chat, deploys, and status updates
• draft customer-impact language for review
• prepare mitigation options with evidence and risk
• stop when the incident commander gives a direct instruction

The skill can also define roles. If an incident commander is present, the agent should support that person rather than issuing commands into the room. If there is no incident commander, the skill can recommend establishing one before the agent starts deep diagnosis.

Community examples show why this matters. One r/SRE thread complains that too much process can slow responders when runbooks become hyper-specific and people hesitate over which one to use (r/SRE process discussion). Another describes runbooks linked directly from alerts as more useful than separate wiki pages nobody remembers at 3 a.m. (r/SRE runbooks-from-alerts discussion). A good DevOps skill should reduce that switching cost without becoming a rigid script that responders follow blindly.

DevOps skills benefit from local references:

• references/services.md for service ownership and dashboards.
• references/environments.md for environment names and safety rules.
• references/deploy-checklist.md for release-specific gates.
• scripts/read-health.sh for safe read-only checks.
• scripts/collect-logs.sh for bounded log retrieval.

The skill should explain which scripts are safe and what inputs they require. If a script can mutate state, the skill should require approval before running it.

Use scripts for deterministic checks: parsing Terraform plan JSON, reading Kubernetes rollout status, collecting bounded logs, or checking GitHub workflow results. Use SKILL.md for judgment: which signal matters, what evidence is enough, when to escalate, and when to stop.

Anthropic's engineering post describes agent skills as organized folders of instructions, scripts, and resources that agents can discover and load dynamically (Anthropic engineering). DevOps is where that folder structure becomes more than packaging. It is the difference between "look around production" and "read these exact sources, in this order, with these stop rules."

Before publishing a DevOps skill, ask:

• Does the skill clearly say whether it is read-only, approval-required, or allowed to act?
• Does it distinguish local, staging, production, sandbox, and disaster-recovery environments?
• Does it name forbidden commands such as terraform apply, terraform destroy, kubectl delete, direct database writes, or secret reads?
• Does it require timestamps, commit SHAs, deployment IDs, metric windows, and affected services?
• Does it tell the agent which source wins when CI, dashboards, and chat disagree?
• Does it protect secrets, logs with customer data, and copied incident transcripts?
• Does it include escalation rules for severity, customer impact, missing access, and ambiguous ownership?
• Does it make final output reviewable: commands run, evidence found, confidence, blockers, and next action?

Do not use a DevOps skill to bypass approvals, grant broad production access, or hide operational judgment inside an agent. Use one when the procedure is already known, repeatable, and safer when written down.

The best first DevOps skill is usually a verifier, not an actuator: canary checks, incident summaries, release readiness, or read-only triage.

Avoid DevOps skills when the team does not yet know the procedure. If every incident becomes a debate about ownership, alert quality, SLOs, deployment strategy, or rollback policy, write the human runbook first. A skill can encode policy; it cannot supply missing operational ownership.

Also avoid broad "autonomous remediation" skills until the failure mode is boring and well understood. Restarting a stuck worker, rotating a drained node, or reverting a known-bad feature flag might eventually be safe behind strong controls. General incident mitigation is not.

A good first DevOps skill is release-readiness:

---
name: release-readiness
description: Review CI, deployment gates, migrations, infrastructure changes, and release notes before a staging or production deploy. Read-only unless explicitly approved.
---

Confirm repository, pull request, commit SHA, target environment, and deploy window.
Read changed files, CI jobs, deployment workflow, release notes, migrations, IaC changes, and feature-flag changes.
Check whether the deployment target uses protected environment rules.
Return:
- go/no-go
- blocking findings
- warnings
- commands or pages inspected
- evidence links
- approval-required actions

Stop if the target environment is ambiguous, CI is unavailable, production credentials are missing, or the requested action would mutate production.

That skill is narrow enough to test and valuable enough to reuse. It can later grow into variants: post-deploy-canary, terraform-plan-review, incident-timeline, kubernetes-rollback-prep, or sre-postmortem-draft.

The durable rule is simple: let deployment systems deploy, let infrastructure tools enforce state, let incident commanders command, and let the skill make the agent disciplined. For authoring mechanics, How to Write an Agent Skill That Actually Works covers the skill contract, while How to Test an Agent Skill Before You Publish It explains how to validate behavior before trusting it in real workflows.