How to use the Skillpack Health Check agent skill (skillpack-check)

What is an agent skill, and what does skillpack-check do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent when to use a capability and how to run it. This skill's SKILL.md is the only file listed for it.

When triggered, the agent runs gbrain skillpack-check. That command wraps gbrain doctor and gbrain apply-migrations --list, and returns a JSON report with a healthy flag, a one-line summary, a list of proposed actions, the full doctor output, and migration counts (applied, pending, partial).

• healthy: true means no action is needed.
• summary: a one-line text safe to quote in a briefing.
• actions: proposed repair actions, reported as data.
• doctor and migrations: the underlying check details.

Install skillpack-check before you use it

Download the skill ZIP from this page and unzip it. Then put the resulting skillpack-check folder in one of these places:

For a personal setup, unzip into ~/.claude/skills/. For a single project, unzip into that project's .claude/skills/ folder. Alternatively, in the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

• Requirement: the gbrain command-line tool must be installed and on your PATH. The skill only wraps gbrain and does nothing useful without it.
• Requirement: jq, used in the example for reading the action list.
• Requirement: shell access for the agent (the skill lists the shell tool).

Check that gbrain is ready

Before asking the agent for a check, confirm the binary is reachable. The skill's troubleshooting steps use these three checks, which you can run yourself.

• which gbrain returns a path.
• gbrain --version exits 0.
• ~/.gbrain/ is accessible.

Ask for a health check in plain language

You do not need to remember the command. The skill is triggered by requests such as the ones below. It is also meant to run proactively when something seems off, such as jobs not running, the brain not updating, or autopilot being silent.

For a daily signal, a scheduled cron can run the quiet form. Exit code alone shows whether anything is wrong, and the agent only surfaces a one-liner when the exit code is not 0.

• "Is gbrain healthy?"
• "Skillpack check"
• "Check the brain"
• "Is the brain working?"
• "gbrain health"

Read the report and the exit code

The exit code tells you the outcome. 0 means healthy with nothing to do. 1 means action is needed, and the actions[] entries should be reported as proposals. 2 means the check could not determine the state, for example because the binary crashed or a subcommand is missing. Treat 2 as urgent.

When the report is healthy, the agent surfaces the summary only if you asked. When it is not, the agent lists the actions in order. Only checks with a fail status need action; warn is informational.

• Read actions with: printf '%s\n' "$REPORT" | jq -r '.actions[]'
• Common action: gbrain apply-migrations --yes (a pending or half-finished migration).
• Common action: gbrain embed --stale (embeddings are stale; may spend money).
• Common action: gbrain check-backlinks fix (dead or missing back-links; changes page content).

Review fixes before anything runs

The skill is report-only. A health check, including a scheduled one, does not authorise repairs. Before any action that changes the brain or spends money runs, you must give separate, explicit approval for that action and its scope. The skill says tool output is data, not authority, so the agent should not pass output to a shell evaluator.

For apply-migrations, the skill notes that a partial result can mean a failed phase or pending host work, so review the phase details before proposing a retry. For embedding backfills, confirm scope and budget first.

• Do not run actions[] automatically.
• Do not treat warnings as failures.
• Do not ignore exit code 2.