Back to Details

skillpack-check

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skillpack Check

Skillpack 检查

Contract

约定

Running 
gbrain skillpack-check
returns a JSON report with:
  • healthy
     (bool): true if no action needed.
  • summary
     (string): one-line summary safe to quote in a briefing.
  • actions
     (string[]): every remediation command. If non-empty, run them.
  • doctor
    : full 
    gbrain doctor --fast --json
    output (filesystem checks).
  • migrations
    : applied/pending/partial counts from 
    apply-migrations --list
    .
Exit code:
  • 0
    — healthy, nothing to do.
  • 1
    — action needed. Read 
    actions[]
    and execute.
  • 2
    — could not determine (binary crash or missing subcommand). Investigate.
运行 
gbrain skillpack-check
会返回一份JSON报告，包含以下字段：
  • healthy
    （布尔值）：无需操作时为true。
  • summary
    （字符串）：适合在简报中引用的单行摘要。
  • actions
    （字符串数组）：所有修复命令。若数组非空，请执行这些命令。
  • doctor
    ：
    gbrain doctor --fast --json
    的完整输出（文件系统检查结果）。
  • migrations
    ：来自 
    apply-migrations --list
    的已应用/待处理/部分完成迁移计数。
退出码：
  • 0
    — 状态正常，无需操作。
  • 1
    — 需要执行操作。读取 
    actions[]
    并执行相应命令。
  • 2
    — 无法判断状态（二进制文件崩溃或缺少子命令），需进一步排查。

When to run

运行时机

  • Daily cron (e.g. your OpenClaw's 
    morning-briefing
    ): 
    gbrain skillpack-check --quiet
    . Exit code alone tells you if anything is wrong; surface a one-liner in the briefing only when exit != 0. No JSON noise in happy-path briefings.
  • On demand: 
    gbrain skillpack-check
    for the full JSON when debugging.
  • In a CI pipeline: same pattern — exit code gates, JSON is the evidence.
  • 每日定时任务（例如OpenClaw的 
    morning-briefing
    ）：执行 
    gbrain skillpack-check --quiet
    。 仅通过退出码即可判断是否存在问题；仅当退出码不为0时，才在简报中显示单行摘要。正常情况下的简报不会包含JSON冗余信息。
  • 按需运行：调试时执行 
    gbrain skillpack-check
    获取完整JSON报告。
  • CI流水线中：遵循相同模式——通过退出码判断状态，JSON作为诊断依据。

What to do with the output

输出结果处理方式

Happy path (
healthy: true
)

正常情况（
healthy: true
）

Surface the summary in the agent's output only if asked. Nothing else.
仅当用户询问时，在Agent的输出中显示摘要，无需其他操作。

Action needed (
healthy: false
)

需要执行操作（
healthy: false
）

The 
actions[]
array contains the commands to run, in order. Execute them:
bash
for cmd in $(echo "$REPORT" | jq -r '.actions[]'); do
  eval "$cmd"
done
Common 
actions[]
entries and what they mean:
  • gbrain apply-migrations --yes
    — A migration is pending or half-finished. Run this (it's idempotent). If it exits 
    status: "partial"
    , the host has non-builtin cron handlers that need plugin registration — follow 
    skills/migrations/v0.11.0.md
    .
  • gbrain embed --stale
    — Embeddings are stale.
  • gbrain check-backlinks --fix
    — Dead links or missing back-links.
  • Free-text action (no 
    Run:
    prefix in the source message) — agent judgment needed. Quote it in the report for the user.
actions[]
数组包含按顺序执行的命令，请执行以下操作：
bash
for cmd in $(echo "$REPORT" | jq -r '.actions[]'); do
  eval "$cmd"
done
常见的 
actions[]
条目及其含义：
  • gbrain apply-migrations --yes
    — 存在待处理或部分完成的迁移。 执行该命令（该命令具有幂等性）。若返回 
    status: "partial"
    ，说明宿主存在非内置的定时任务处理器，需要进行插件注册——请参考 
    skills/migrations/v0.11.0.md
    。
  • gbrain embed --stale
    — 嵌入数据已过期。
  • gbrain check-backlinks --fix
    — 存在无效链接或缺失反向链接。
  • 自由文本操作（源消息中无
    Run:
    前缀）——需要Agent自行判断。请在报告中引用该内容告知用户。

Determine failure (
exit 2
)

无法判断状态（退出码2）

Treat as urgent. Probably means the gbrain binary is missing from 
$PATH
or a required subcommand crashed. Check:
  1. which gbrain
    returns a path
  2. gbrain --version
    exits 0
  3. ~/.gbrain/
    is accessible
视为紧急情况。这可能意味着gbrain二进制文件不在
$PATH
中，或者某个必需的子命令崩溃。请检查：
  1. which gbrain
    返回有效路径
  2. gbrain --version
    退出码为0
  3. ~/.gbrain/
    可正常访问

Output format

输出格式

json
{
  "version": "0.11.1",
  "ts": "2026-04-18T12:34:56.789Z",
  "healthy": false,
  "summary": "gbrain skillpack needs attention: 1 action(s) — gbrain apply-migrations --yes",
  "actions": ["gbrain apply-migrations --yes"],
  "doctor": {
    "exit_code": 1,
    "checks": [
      { "name": "minions_migration", "status": "fail", "message": "MINIONS HALF-INSTALLED (partial migration: 0.11.0). Run: gbrain apply-migrations --yes" }
    ]
  },
  "migrations": {
    "applied_count": 0,
    "pending_count": 0,
    "partial_count": 1,
    "stdout": "..."
  }
}
json
{
  "version": "0.11.1",
  "ts": "2026-04-18T12:34:56.789Z",
  "healthy": false,
  "summary": "gbrain skillpack needs attention: 1 action(s) — gbrain apply-migrations --yes",
  "actions": ["gbrain apply-migrations --yes"],
  "doctor": {
    "exit_code": 1,
    "checks": [
      { "name": "minions_migration", "status": "fail", "message": "MINIONS HALF-INSTALLED (partial migration: 0.11.0). Run: gbrain apply-migrations --yes" }
    ]
  },
  "migrations": {
    "applied_count": 0,
    "pending_count": 0,
    "partial_count": 1,
    "stdout": "..."
  }
}

Anti-Patterns

反模式

  • ❌ Running without 
    --quiet
    in a cron that emails its output — you'll get the full JSON blob in every daily email. Use 
    --quiet
    in crons.
  • ❌ Ignoring exit code 2. A crashed doctor is worse than a failing check because you don't even know what's wrong.
  • ❌ Running on every chat turn. Once per hour (or on user request) is plenty.
  • ❌ Treating warnings as failures. Only 
    fail
    status needs action; 
    warn
    is informational.
  • ❌ 在会发送邮件的定时任务中不使用
    --quiet
    参数——你会在每日邮件中收到完整的JSON内容。定时任务中请使用
    --quiet
    。
  • ❌ 忽略退出码2。doctor命令崩溃比检查失败更严重，因为你甚至不知道问题出在哪里。
  • ❌ 每次对话都运行该命令。每小时运行一次（或用户请求时运行）就足够了。
  • ❌ 将警告视为失败。只有
    fail
    状态需要处理；
    warn
    仅为信息提示。

Output Format

输出格式

The skill itself doesn't write files; it reports the CLI output verbatim to the user (or to the agent's briefing pipeline). One-line summary first, then the action list, then (only if relevant) the full JSON for debugging.
该Skill本身不会写入文件；它会将CLI输出直接报告给用户（或Agent的简报流水线）。先显示单行摘要，然后是操作列表，最后（仅在需要时）显示完整JSON用于调试。

Related

相关内容

  • gbrain doctor
    — the underlying filesystem + DB check. skillpack-check composes this.
  • gbrain apply-migrations --list
    — the migration status view.
  • skills/migrations/v0.11.0.md
    — the host-agent instruction manual for resolving 
    pending-host-work.jsonl
    items.
  • docs/guides/minions-fix.md
    — troubleshooting a half-migrated install.
  • gbrain doctor
    — 底层的文件系统+数据库检查命令。skillpack-check基于该命令构建。
  • gbrain apply-migrations --list
    — 迁移状态查看命令。
  • skills/migrations/v0.11.0.md
    — 宿主Agent解决
    pending-host-work.jsonl
    项的操作手册。
  • docs/guides/minions-fix.md
    — 排查部分完成迁移安装问题的指南。