How to use the Arbor agent skill: setup, triggers and examples

What is an agent skill, and what does Arbor make the agent do?

An agent skill is a folder of instructions and optional scripts that an AI agent loads when a task matches the skill's description. Arbor's SKILL.md describes an Autonomous Optimization loop: start from an existing artifact and a measurable objective, then improve it over many rounds of experiment and evaluation with limited step-by-step supervision.

The agent acts as a long-lived coordinator. It keeps the research state in a persistent hypothesis tree rather than in conversation history, proposes falsifiable child hypotheses, and hands each one to a short-lived executor that tests it in an isolated git worktree and reports evidence back.

• Records each hypothesis, the insight it produced and the artifact version that realizes it
• Conditions new ideas on validated insights and pruned dead ends
• Uses a development evaluator to search and a held-out test evaluator only at the merge gate

Install the Arbor skill from a ZIP file

Download the ZIP for skills/arbor from the directory page, then choose one of two locations. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you start

The bundled scripts/tree.py state manager needs Python 3.10 or newer and uses only the standard library. Git is needed for experiment worktrees. You must supply your project's own development and test evaluator commands. Model provider credentials and network access are needed only for autonomous model calls.

The optional arbor-agent CLI is a separate installation. The skill's reference notes say the bundled helper requires no provider key, while the native upstream runtime does need model access.

• Python 3.10+ for the state manager
• Git for experiment worktrees
• Your own dev and test evaluator commands
• Optional: separate arbor-agent CLI installation
• Provider credentials and network access only for autonomous model calls

Trigger the skill with a natural request

You do not need special syntax. Describe a concrete artifact, an objective, a way to score candidates and the fact that you expect many experiments. The skill's description matches requests about iterative improvement under an evaluator.

Requests that fit well describe a measurable target. Requests that fit poorly ask for a single fix or open-ended ideas, and the skill says to handle those directly or use hypothesis-generation or scientific-brainstorming instead.

• "Improve our search harness's answer accuracy over about 20 experiments. The dev eval is python eval.py --split dev and the held-out one is --split test."
• "Tune this training recipe to reach the target loss in fewer steps, and keep an auditable record of what we tried."
• "Optimize our data filtering pipeline using downstream model scores, with a clean test split I'll provide."

Set up the run: the task tuple and the state manager

Before experiments, the skill pins down four items: the initial material M_0 (under git and currently runnable), the objective O with its metric direction, a development evaluator E_dev that is fast and repeatable, and a held-out test evaluator E_test that is used only at the merge gate. It asks you only for decisions that are missing.

The state manager is run through the ARBOR_TREE variable, which points to the absolute path of scripts/tree.py. The skill's example initializes a run with an objective, the two evaluator commands, a material path, a metric direction, branching, maximum depth and a cycle budget. Replace the example evaluator commands with your own.

• Freeze the evaluator, dataset split and metric before search, and record their versions with each score
• Record the baseline score on the fixed gate protocol before search begins
• Keep raw evaluator output, seeds, split IDs and evaluator version alongside .arbor/

Run the coordinator loop: observe, ideate, execute, judge, merge, record

Each cycle starts by re-reading the tree with the observe command, so the agent works from recorded state rather than memory. The agent then proposes falsifiable child hypotheses under a promising parent, dispatches executors to test them in separate worktrees, judges the evidence, merges only gate-approved changes and records the cycle. The skill notes that only the coordinator writes shared state, one step at a time.

The state manager records scores and decisions. It does not run evaluators, create worktrees, verify Git refs or merge Git branches. Those actions are performed by the agent and your tools.

• observe: prints the objective, insights, active frontier, evidence, pruned lessons and current best artifact
• cycle: run once per cycle to track the budget
• Start with a small budget of about 10 to 20 cycles

Read the results honestly: the held-out gate and development-only runs

The held-out merge gate admits a change only when it improves on the test evaluator. A candidate that wins on the development set but not the test set is a warning that the search is exploiting the feedback signal, not a success.

If you have no defensible holdout, the skill says to label results as development-only. Repeated merge decisions on the same held-out set can still adapt the search to that set, so keep a final untouched evaluation set for the final claim or disclose that the result was selected using repeated gate feedback.

Safety notes: scripts, Git changes and network use

The skill runs scripts and uses the network. The bundled state manager is a Python script that reads and writes JSON state under .arbor/ in your experiment project. Your evaluator commands and the executors' code changes run in your environment, so review the commands you give the agent before it runs them.

Network access is needed only for autonomous model calls through a provider. Executors work in isolated Git worktrees, which keeps file changes separate, but the skill notes that worktrees do not prevent statistical leakage from repeated use of the same held-out set.

• Review evaluator commands before running long searches
• Keep provider credentials out of shared files
• The helper has no multi-writer locking, so run it from one coordinator at a time