Design Reusable AI Skills for Ops Automation

Package prompts, scripts, and docs into reusable AI skills so your AI agent runs SSH and server operations the same reliable way every time. A practical guide with a real DevOps example, built on Temp

AI agents are great at one-off answers and terrible at doing the same task the same way twice. Ask an agent to "check why the server is slow" on Monday and again on Friday, and you'll get two different investigations, two different command sets, and two different levels of thoroughness.

AI skills fix this. A skill packages the knowledge, the exact scripts, and the "when to use me" trigger into one reusable unit your agent loads on demand. Instead of re-explaining your runbook every time, you teach the agent once and it executes reliably forever.

This guide shows you how to design skills that turn flaky, ad-hoc AI help into dependable, repeatable ops automation — whether you use the built-in Tempest AI Assistant or an external agent like Codex or Claude Code.

What is an AI skill?

An AI skill is a self-contained, reusable capability you give an AI agent. In practice it is a small folder:

diagnose-high-load/
├── SKILL.md          # what it does, when to use it, how it works
├── collect.sh        # gather load, top processes, IO wait
└── summarize.py      # turn raw output into a ranked diagnosis

The SKILL.md is the brain. Everything else is the muscle. When the agent decides the skill is relevant — based on its description — it reads SKILL.md, then runs the scripts it references.

This model was popularized by coding agents such as Claude Code, which load skills from a skills/ directory, each with a SKILL.md whose frontmatter tells the model when to reach for it. The same pattern works beautifully for infrastructure and ops, where "do it exactly like the runbook" matters even more than in code.

Skill vs. prompt vs. script

Approach	Reusable?	Deterministic?	The AI knows when to use it?
One-off prompt	❌ retyped each time	❌ varies per run	❌
Bare script	✅	✅	❌ agent doesn't know it exists
AI skill	✅	✅ scripts + ✅ guidance	✅ via its description

A skill is the only option that is reusable, deterministic and self-advertising. That last property — the agent knowing when to use it — is what makes skills scale.

Why reusable skills beat one-off prompts

1. Consistency. The same steps run every time, in the same order, with the same thresholds.

2. Safety. You review the scripts once. The agent runs vetted commands instead of improvising rm -rf at 2 a.m.

3. Speed. No re-explaining context. The agent loads the skill and goes.

4. Team leverage. One engineer writes the skill; the whole team's AI inherits it.

5. Portability. A well-formed skill is just Markdown + scripts, so it works across agents — the built-in assistant today, an external agent tomorrow.

Anatomy of a great SKILL.md

The SKILL.md file is where skills succeed or fail. Give it frontmatter and a body:

---
name: diagnose-high-load
description: >
  Diagnose high CPU or load average on a Linux host. Use when a server feels
  slow, load average is elevated, or a monitoring alert fires for CPU/IO.
  Identifies the top offending processes and IO wait, and proposes next steps.
---

# Diagnose High Load

## When to use
Trigger this when: load average > number of cores, a CPU/latency alert fires,
or the user says the box is "slow" / "pegged" / "hanging".

## How it works
1. Run `collect.sh` on the target host to snapshot load, top, iostat, and the
   busiest processes.
2. Pipe the raw output through `summarize.py` to rank likely root causes.
3. Report the top suspect + a recommended action. Do NOT restart services
   without confirmation.

## Guardrails
- Read-only. Never kill processes or restart services automatically.
- If IO wait dominates, suggest checking disk health, not CPU.

The three fields that matter most

• name — a short, kebab-case identifier. Stable; don't rename casually.

• description — the single most important line in the whole skill. This is what the agent reads to decide whether to load it. Write it for discovery: name the symptoms, the trigger words, and the outcome. A vague description ("helps with servers") never gets picked; a specific one ("use when load average is elevated or a CPU alert fires") gets picked exactly when it should.

• When-to-use (in the body) — reinforce the triggering conditions so the model doesn't misfire.

The description is a search query the model runs against your skill library. Optimize it the way you'd optimize a page title — for the exact terms the situation will surface.

Design your first skill in 5 steps

1. Pick a task you repeat. The best first skill is a runbook you've explained to a teammate more than twice.

2. Write the scripts first. Get collect.sh working by hand over SSH. Make it idempotent — safe to run twice.

3. Write the description last, and sweat it. List the symptoms and trigger words. This is your discovery surface.

4. Add guardrails. Explicitly state what the skill must not do (no restarts, no writes, no deletes without confirmation).

5. Store it where the agent can find it — a folder in Tempest Drive (more below).

Best practices for reliable, safe skills

• One skill, one job. A skill that "does everything" gets loaded for the wrong reasons. Split broad skills.

• Idempotent scripts. Running twice should be safe. Prefer read-only collection; separate any mutation into a clearly-named step.

• Least privilege. Keep destructive capabilities in their own skill with heavy guardrails and required confirmation.

• Deterministic output. Have scripts emit structured, stable text (or JSON) so the AI's summary is consistent run to run.

• Pin the environment. State the target OS/shell assumptions in SKILL.md; don't let the agent guess.

• Name for the trigger, not the mechanism. diagnose-high-load beats run-top-and-iostat — the agent matches on the problem, not the tool.

A real example you can copy

Goal: when a Linux box is slow, find the culprit safely.

collect.sh:

#!/usr/bin/env bash
# Read-only load snapshot. Safe to run repeatedly.
set -euo pipefail
echo "== uptime =="; uptime
echo "== top (5s) =="; top -b -n1 | head -20
echo "== iowait =="; iostat -xz 1 2 2>/dev/null | tail -30 || echo "iostat not installed"
echo "== top mem/cpu procs =="; ps aux --sort=-%cpu | head -10

summarize.py ranks likely causes from that output — CPU-bound vs IO-bound vs memory pressure — and names the top offending process, emitting a stable, sectioned report. SKILL.md ties them together with a description that says use me when the box is slow or a CPU alert fires and a guardrail that says read-only, never restart anything.

Now any time a server feels slow, the agent loads this one skill and runs the same disciplined investigation — no improvisation.

Where to store skills: Tempest Drive

A skill is only reusable if your agent can find it. Tempest Drive — the same store behind Snippets & Scheduled Runs — is a natural home: it holds documents and scripts as first-class items, organized into folders. And a skill is just a folder:

Drive/
└── skills/
    └── diagnose-high-load/
        ├── SKILL.md      (Markdown)
        ├── collect.sh    (Shell)
        └── summarize.py   (Python)

Because Drive items carry a folder path and a language (Markdown, Shell, Python, and more), a skill needs no special format — it's an ordinary folder of ordinary files. Drive syncs end-to-end encrypted across your devices, so a skill you write on your laptop is available to your agent everywhere, and shareable with your team's vault.

That means:

• You can author and edit skills in the Drive UI, with folders and breadcrumbs.

• Your AI can read a skill to execute it — and save new skills back to Drive as it learns your environment.

Using skills across agents

Skills are portable by design, so the same folder works no matter which brain is driving:

• Tempest AI Assistant — reference a skill's SKILL.md and scripts as context, and the assistant follows the runbook, using its terminal and file tools to run the steps on the target host.

• External agents such as Codex or Claude Code, connected over the Tempest MCP server — these manage their own skills on disk. Point them at the same skill folder, or let them save skills to Drive so your whole toolchain shares one library.

Because a skill is just Markdown plus scripts, there's no lock-in: write it once, run it with any agent that can read a file and run a command.

Frequently asked questions

What is an AI skill? A reusable capability packaged as a folder — a SKILL.md describing what it does and when to use it, plus the scripts it runs. The agent loads it on demand based on the description.

How is a skill different from a prompt? A prompt is retyped and varies each run. A skill is stored once, runs deterministic scripts, and advertises itself to the agent via its description, so it's picked automatically at the right moment.

What should go in SKILL.md? Frontmatter with a name and a sharp description, plus a body covering when to use it, how it works, and guardrails (what it must never do).

How do I make an AI skill safe? Keep it least-privilege and idempotent: read-only diagnostics by default, destructive actions isolated into their own guarded skill that requires confirmation.

Where do I store AI skills? Anywhere the agent can discover them — most naturally in Tempest Drive, which stores each skill as a synced, optionally shared folder of Markdown and scripts.

Can different AI agents share the same skill? Yes. A skill is just Markdown plus scripts, so the built-in assistant and external MCP agents can all read and run the same skill folder.

Conclusion

The jump from "AI that helps sometimes" to "AI that reliably runs your ops" is skills. Package your runbooks as folders — a sharp SKILL.md plus vetted, idempotent scripts — store them in Tempest Drive, and any agent you use inherits your team's operational knowledge.

Start with one skill for a task you repeat. Sweat the description. Add guardrails. Then watch your AI do the same job, the same safe way, every single time.