Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/garrytan/gbrain --skill gbrain-advisorAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
gbrain Advisor
Convention: See skills/conventions/brain-first.md. This skill is the proactive voice of the brain — it tells the owner how to run it better.Contract
This skill guarantees:
- Read-only.
gbrain advisornever mutates. It computes a ranked list of
actions from existing brain state.
- Print, never execute. You SHOW the user the findings and ASK before running
any fix. The user owns every decision.
- Bounded nagging. On a cadence, surface only what changed or what's
critical; don't repeat an ignored low-severity item every run.
When to run
- On demand when the user asks "how do I get more out of this brain?"
- On a weekly cadence via the cron recipe below (even idle brains get a
"here's how to run this better" ping).
- Monthly, the advisor also surfaces the backup-coverage verdict (`gbrain
backup status` — which knowledge repos have no git remote); relay any warn.
How to run it
gbrain advisor --jsonExit code is the severity gate (E2): 0 clean, 1 warn, 2 critical. The JSON payload is { version, generated_at, worst, findings: [...] }. Each finding has:
severity—critical|warn|infotitle— one-line why-it-mattersfix.command_argv— the exact command to fix it (a structured argv)fix.dispatch_id— present when the fix is safe to run via--apply
What to do with the findings
- Read the findings, highest severity first.
- Summarize the top 1-3 to the user in their own channel/voice. Lead with any
critical item (e.g. pending migrations).
- For each, show the
fix.command_argvand ask whether to run it. - If they say yes and the finding has a
fix.dispatch_id, you may run it
locally with an explicit confirm:
gbrain advisor --apply <dispatch_id>--apply is local-only, runs the fix as a structured argv (no shell), and confirms first. Findings without a dispatch_id are not auto-runnable — run their fix.command_argv yourself after the user agrees.
- Never run a fix the user didn't approve.
Cron recipe (weekly checkup)
Install a weekly job via the cron-scheduler skill. Keep the prompt THIN — the job just reads this skill and runs the advisor:
- Schedule: weekly, one quiet-hours-respecting slot (e.g. Monday 09:00 local).
- Job prompt:
Read skills/gbrain-advisor/SKILL.md and run gbrain advisor --json. If anything is critical or new since last run, ping me with the top items and the exact fix commands. Ask before fixing. - Idempotent: the advisor is read-only, so a double-fire is harmless.
The advisor records a local run history, so on each fire you can tell the user what is new since last run rather than re-listing everything.
Output Format
When you surface advisor findings to the user, lead with severity and keep it scannable:
🧠 gbrain checkup — 2 things worth your attention
CRITICAL Schema migrations are pending.
Fix: gbrain apply-migrations --yes (want me to run it?)
WARN gbrain 0.44 is available (you're on 0.43).
Fix: gbrain upgrade- One block per finding, highest severity first.
- Always show the exact
fixcommand and ASK before running it. - If nothing is pressing, say so in one line ("brain looks healthy") — don't
manufacture work.
When it fails
Follow the agent operator protocol for any gbrain error code, exit code, [AGENT] block or notice block. Specific to this skill:
- A
criticalfinding (pending migrations) carries a fix such asgbrain apply-migrations --yes: ask the user before running it; findings without adispatch_idare not auto-runnable. gbrain advisorcannot reach the brain (GBRAIN_DB_ACCESSmarker): route to the db-repair skill instead of reporting "no findings".
Anti-Patterns
- Running a fix without asking. The advisor is read-only by contract. Never
run --apply (or any fix command) without the user's explicit yes.
- Dumping the raw JSON at the user. Translate findings into their voice; lead
with what matters.
- Re-nagging ignored low-severity items every run. Use the "new since last
run" delta; respect the user's prior non-action.
- Treating `info` like `critical`. Only block/insist on
criticalfindings
(pending migrations). info is a gentle nudge.
- Calling the MCP `advisor` op for workspace install state. Over MCP the
advisor returns brain-state signals only; uninstalled-skill findings are a local-CLI concern.