Guide · Agent skill
How to use the Mac Vitals Diagnostics agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
Vitals is an agent skill that lets an AI agent inspect the performance of a macOS computer and explain what is slowing it down. It is for Mac users whose machine feels slow, hot or loud, and for developers chasing chronic slowdowns. After this guide you will know what the skill does, how to install it, how to phrase requests so it triggers, and what it will and will not do on your machine.
Mac Vitals Diagnosticsdanielmiessler/LifeOS · MIT Download the skill Quick start
- 1Confirm requirements. Check that you are on macOS and have the Bun runtime and Claude Code or another SKILL.md-compatible agent.
- 2Download the ZIP. Download the Vitals ZIP from this page.
- 3Unzip into the skills folder. Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project.
- 4Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 5Ask in plain words. Describe the symptom, for example "my Mac is slow" or "why are my fans loud".
- 6Review the verdict. Read the culprit or verdict and the evidence behind it.
- 7Approve any fix. Decide on each recommended command or setting yourself; the skill does not run them.
What is an agent skill, and what does Vitals make the agent do?
An agent skill is a folder with a SKILL.md file that tells a compatible AI agent when to use it and how. Vitals is a macOS performance skill: when you ask about a slow Mac, the agent runs a small read-only command-line tool that gathers CPU, GPU, memory, energy, thermal, disk and startup data.
Instead of returning a raw dump of numbers, the agent interprets them against stored thresholds. It names the likely culprit, such as a runaway process, memory pressure or heat throttling, and suggests fixes for you to approve. It never kills processes or changes settings itself.
Install the Vitals skill
Download the ZIP from this page and unzip it into one of these locations. For a personal install, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/Vitals/
- Project install: .claude/skills/Vitals/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Check the requirements before you start
Vitals needs macOS, the Bun runtime (the script is run with bun), and Claude Code or another agent that reads SKILL.md files. It relies on macOS-specific commands such as pmset, ioreg and launchd, so it will not work on Windows or Linux.
- macOS
- Bun runtime
- Claude Code or another SKILL.md-compatible agent
Trigger the skill with natural requests
You do not need a special command. Describe the problem in plain words. The skill matches phrases such as "mac slow", "what's eating CPU", "fans loud", "memory pressure", "check my mac" and "startup items". Its routing covers three paths: a quick health check, a culprit hunt for a specific symptom, and a deep diagnosis for chronic or recurring slowness.
Name the symptom you noticed when you can. A report can then say which finding explains it, or say plainly that none of the collected evidence does.
- Quick check: "how's my system doing?" or "check my mac"
- Culprit hunt: "my Mac is dragging, what's going on?" or "why are my fans so loud?"
- Deep diagnosis: "full diagnosis" or "deep check" for chronic slowness
Run the tool directly (optional)
The agent calls the CLI for you, but you can run it yourself to see the same data. The subcommands are check (fast snapshot, under 1s), hogs (live per-process CPU and energy, about 3s), gpu, memory, disk, thermal, startup, and full (everything, about 4s). The flags --json and --top N are also available.
- check: fast snapshot
- hogs: per-process CPU and energy
- full --top 15: everything, no sudo
bun ~/.claude/skills/Vitals/Tools/Vitals.ts full --top 15Understand what the reports contain and what they do not do
Reports lead with a verdict or culprit. A health check returns a one-screen 🟢/🟡/🔴 verdict with per-subsystem lines. A culprit claim must be backed by the process's live numbers and a corroborating system signal. Normal macOS behaviour, such as cache-filled memory, kernel_task cooling, or Spotlight indexing, is named as normal.
The tool is read-only by contract. Every remediation is a specific command or setting offered for your approval. The default path needs no sudo; the sudo leg (powermetrics, sfltool) runs only with your consent and is skipped cleanly if you decline.
Safety notes: scripts, sudo and network
Vitals runs scripts: the Bun tool executes macOS commands to read system state. It does not use the network. It does not kill, renice, unload or write system state. Review the Tools/Vitals.ts file if you want to confirm this before installing.
Customisations go in <configRoot>/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/Vitals/, where configRoot is $CLAUDE_CONFIG_DIR when set, otherwise ~/.claude. Files there override the defaults when that directory exists.
- Runs scripts: yes
- Uses network: no
- Sudo is optional and needs your consent
Tips for useful results
Give the symptom, not a guess at the cause. Say "fans loud when I open the browser" rather than "it's the browser", so the report can test the claim.
Accept a "nothing is actually wrong" answer. The skill is designed to say so when the evidence does not support a problem.
Expect a few seconds of wait for live sampling. The hogs and full subcommands take about 3s and 4s.
What people use it for
- Finding which app is using most of the CPU when the Mac feels sluggish
- Explaining loud fans that come from kernel_task cooling a hot machine
- Checking whether memory pressure or swap is causing slowdowns
- Getting a one-screen health summary before starting a long task
- Investigating startup items or launch agents that may add load at login
Frequently asked questions
How do I install the Vitals agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What are the requirements for the Vitals skill?
You need macOS, the Bun runtime because the script is run with bun, and Claude Code or another agent that reads SKILL.md files. It does not work on Windows or Linux because it relies on macOS-specific commands such as pmset, ioreg and launchd.
Is the Vitals skill free?
The source lists the item's licence as MIT. Check the licence file in the repository for the exact terms before you rely on it.
Does Vitals change anything on my Mac?
No. The tool is read-only by contract and never kills processes, renices them, unloads agents or writes system state. Any fix it suggests is offered for your approval and you run it yourself.
Does Vitals need sudo or network access?
The default path needs no sudo. A sudo leg using powermetrics and sfltool runs only with your consent and is skipped if you decline. The skill does not use the network.
Can Vitals diagnose Wi-Fi or website problems?
No. It explicitly excludes network and Wi-Fi problems, deployed website or app health, and security scanning. It is limited to macOS performance.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Vitals suits Mac users who want a plain-language explanation of a slow, hot or loud machine, and developers chasing recurring slowdowns, provided they run macOS with Bun and a SKILL.md-compatible agent. If you need Wi-Fi diagnosis, website monitoring, Windows or Linux support, or a security scan, pick a different tool.
Download the skill