Menu
Self-evolving skill optimization via SkillOpt-paper-grounded text-space optimizer.
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/garrytan/gbrain --skill skill-optimizerThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Search and write the company knowledge brain. Use for any question about the org, people, projects, decisions, or history, and to persist durable knowledge beyond this scope's notebook.
Take any book (EPUB/PDF), produce a personalized chapter-by-chapter analysis with two-column tables. Left column preserves the chapter content; right column maps every idea to the reader's actual life using brain context. Output is a single brain page at media/books/<slug>-personalized.md plus an optional PDF via brain-pdf.
Structured data research: search sources, extract structured data, archive raw sources, maintain canonical tracker pages, deduplicate. Parameterized via YAML recipes for investor updates, donations, company updates, or any email-to-structured-data pipeline.
Showing SKILL.md
Based on SOC occupation classification
| name | skill-optimizer |
| version | 0.1.0 |
| description | Self-evolving skill optimization via SkillOpt-paper-grounded text-space optimizer. |
| triggers | ["optimize this skill","tune the skill against the benchmark","make the skill better","run skillopt","skillopt for"] |
| mutating | true |
| brain_first | exempt |
Self-evolving skill optimization. Treats SKILL.md as the trainable parameters of a frozen agent. Validation-gated, budget-capped, atomic-versioned.
Based on SkillOpt (arXiv 2605.23904, Microsoft Research, May 2026).
The user wants to:
triggers:, brain_first:) stays invariant.--allow-mutate-bundled AND --held-out <path> with
at least 5 benchmark-disjoint tasks; without the held-out set the run
hard-refuses (exit 2). Drop --allow-mutate-bundled (or pass --no-mutate,
the default for the dream-cycle phase) to write proposed.md for review
instead โ no held-out needed for review-only output.--bootstrap-from-skill
and --bootstrap-from-routing write a sentinel; you must review + STRENGTHEN
the generated judges, delete the sentinel, and re-run with
--bootstrap-reviewed before optimization can use the file.gbrain skillopt <skill-name> [flags]
โ
โโโ Pre-flight gates
โ โโโ working tree clean (or --force)
โ โโโ benchmark valid + D_sel >= 5 (D17)
โ โโโ cost preflight (D3) โ refuses over --max-cost-usd
โ โโโ per-skill DB lock (D14)
โ
โโโ Baseline eval on D_sel (sets best_sel_score)
โ
โโโ for epoch in 1..N:
โ for step in 1..steps_per_epoch:
โ โโโ forward pass: rollouts on D_train batch
โ โโโ backward pass: reflect ร 2 (failures + successes per D7)
โ โโโ rank + clip via LR cosine schedule
โ โโโ apply edits (body-only per D5, tagged result per D9)
โ โโโ validation gate: median-of-3 + epsilon=0.05 (D12)
โ โโโ if accept: commit via D8 history-intent-first
โ โ
โ โโโ slow update (D6) if no improvement this epoch
โ
โโโ Final test eval on D_test โ run receipt
The user will NOT hand-write a benchmark, and you shouldn't start from a blank
file either. When the user says "make skill X better" and
skills/X/skillopt-benchmark.jsonl doesn't exist, generate a starter from the
SKILL.md directly:
gbrain skillopt X --bootstrap-from-skill
skills/X/SKILL.md, infers what the skill produces and what
"good" looks like, and writes ~15 tasks (each with rule judges) to
skills/X/skillopt-benchmark.jsonl plus a # BOOTSTRAP_PENDING_REVIEW
sentinel. No routing-eval.jsonl is needed. Tune the count with
--bootstrap-tasks N (max 50).contains, loose max_chars, or invented headings. Read each task, fix soft
checks, add the must-haves the skill actually requires (real section names,
real length ceilings, min_citations where sources are expected,
tool_called/tool_not_called for tools the skill genuinely uses). A thin
benchmark optimizes for a thin definition of quality โ do not rubber-stamp.# BOOTSTRAP_PENDING_REVIEW, the last line).--split 1:1:1:
gbrain skillopt X --bootstrap-reviewed --split 1:1:1
4:1:5 makes
the validation set floor(15/10)=1, below the D_sel >= 5 floor, and the
optimizer refuses with d_sel_too_small. (4:1:5 needs ~50 tasks.) Add
--dry-run first to preview cost.Benchmark line shape (what the generator writes, one per line):
{"task_id":"x-001","task":"<user prompt>","judge":{"kind":"rule","checks":[{"op":"max_chars","arg":1800},{"op":"contains","arg":"agenda"}]}}
Rule-check vocabulary you'll strengthen with: contains, regex,
section_present, max_chars, min_citations, tool_called, tool_not_called.
Rule judges are deterministic and free, but shallow for skills whose quality is
sequencing, privacy, refusal boundaries, or file placement โ for those, hand-add
richer checks (or an llm judge) during review.
Fallback โ author freehand. If the generated starter is poor (rare, but
possible for very behavior-shaped skills), discard it and write the JSONL
yourself: read the SKILL.md, write ~15 realistic tasks covering the boring middle,
attach >=2 rule checks each, save to skills/X/skillopt-benchmark.jsonl, run with
--split 1:1:1. The human walkthrough lives at
docs/tutorials/improving-skills-with-skillopt.md.
| Situation | Action |
|---|---|
| Skill has no benchmark | gbrain skillopt foo --bootstrap-from-skill โ review + strengthen the judges โ delete sentinel โ gbrain skillopt foo --bootstrap-reviewed --split 1:1:1 (see section above) |
Skill has a routing-eval.jsonl and you want a head start | gbrain skillopt foo --bootstrap-from-routing โ review the generated tasks โ --bootstrap-reviewed (routing tasks test dispatch; tighten them into quality tasks before trusting) |
| Iterating on an existing skill | gbrain skillopt foo --benchmark skills/foo/skillopt-benchmark.jsonl |
| Costly run, want preview | Add --dry-run |
| Bundled skill (skills/ in gbrain repo) | Default writes proposed.md; to commit in place add --allow-mutate-bundled AND --held-out <path> (>=5 benchmark-disjoint tasks) โ else it hard-refuses |
| Want to review changes before applying | Add --no-mutate (writes proposed.md, no held-out needed) |
| Guard against benchmark overfitting | Add --held-out <path> โ a candidate that beats the benchmark but regresses on the held-out set is refused |
| Mid-run crash | gbrain skillopt foo --resume <run-id> |
When invoked, this skill produces:
skills/<name>/SKILL.md (when mutation is allowed)skills/<name>/skillopt/best.md โ pointer copy of current bestskills/<name>/skillopt/versions/vNNNN_eN_sN.md โ per-step snapshotsskills/<name>/skillopt/history.json โ append-only run recordskills/<name>/skillopt/rejected.json โ bounded LRU of rejected edits~/.gbrain/audit/skillopt-YYYY-Www.jsonl โ ISO-week-rotated audit trail--allow-mutate-bundled AND
--held-out. They ship with gbrain and are load-bearing for downstream
agents. In-place mutation requires both flags (held-out >=5 benchmark-disjoint
tasks); without the held-out set the run hard-refuses and points you at
proposed.md.--bootstrap-from-skill and --bootstrap-from-routing have the optimizer
model invent success criteria โ generic and weak by default. Review and
tighten the judges before SkillOpt optimizes against them, or it trains the
skill toward benchmark artifacts instead of real quality.--split 1:1:1 on a ~15-task starter. The default 4:1:5
split drops the validation set below the D_sel >= 5 floor and the run
aborts with d_sel_too_small.runSkillOpt(opts) returns:
{
outcome: 'accepted' | 'no_improvement' | 'aborted' | 'errored',
receipt: {
run_id, skill_sha8, benchmark_sha8, models, cost,
baseline_sel_score, best_sel_score, // real measured baseline (no longer hardcoded 0)
baseline_test_score, test_score, // final held-out test-split eval
},
finalText: string,
mutatedSkillFile: boolean,
proposedPath?: string
}
skillify โ scaffolds a new skill (use BEFORE skillopt)skillpack-check โ audits skill conformance (item 13 surfaces skillopt status)conventions/quality.md โ output quality standards skillopt enforces via judges