> For the complete documentation index, see [llms.txt](https://docs.gotempest.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gotempest.app/zh-cn/productivity/ai-skills-reusable-ops-automation.md).

# Design Reusable AI Skills for Ops Automation

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](/zh-cn/productivity/tempest-ai-assistant.md) or an [external agent like Codex or Claude Code](/zh-cn/productivity/using-ai-agents-to-manage-servers.md).

## 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:

```markdown
---
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](/zh-cn/productivity/snippets-scheduled-runs.md) (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`:

```bash
#!/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](/zh-cn/productivity/snippets-scheduled-runs.md) — 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](/zh-cn/account-and-privacy/end-to-end-encryption.md) 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**](/zh-cn/productivity/tempest-ai-assistant.md) — 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**](/zh-cn/productivity/using-ai-agents-to-manage-servers.md) such as Codex or Claude Code, connected over the [Tempest MCP server](/zh-cn/productivity/install-tempest-mcp-server-in-ai-clients.md) — 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](/zh-cn/productivity/snippets-scheduled-runs.md), 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.