aithy: Skill for Claude Code

GEPA Optimization Codegen Rules (@ax-llm/ax)

Use this skill to generate GEPA optimization code. Prefer the top-level optimize(...) helper for normal code, and use direct AxGEPA / AxBootstrapFewShot only when the user needs low-level optimizer control.

Use These Defaults

• Use optimize(program, train, metric, { studentAI, teacherAI, ... }) for normal generator and flow tuning.
• Prefer ai(), ax(), and flow() for new code.
• Use a strong teacherAI and a cheaper studentAI.
• Pass validationExamples when you have a holdout set.
• Set maxMetricCalls to bound optimizer cost; optimize(...) defaults it to 100.
• Use scalar metrics for one objective and object metrics for Pareto optimization.
• Apply results with program.applyOptimization(result.optimizedProgram!).
• For tree-wide runs, expect optimizedProgram.componentMap.
• Persist artifacts with axSerializeOptimizedProgram(...) and restore them with axDeserializeOptimizedProgram(...) so the same flow works in browsers and Node.
• optimize(...) runs AxBootstrapFewShot -> AxGEPA for small starter sets by default, preserving the demos in result.optimizedProgram.demos.

Critical Rules

• optimize(...) and AxGEPA.compile() work for a single generator and for tree-aware roots such as flows or agents with registered optimizable descendants.
• There is no separate flow-only GEPA optimizer. Use AxGEPA for flows too.
• The metric may return either number or Record<string, number>.
• Keep metrics deterministic and cheap by default.
• Avoid extra LLM calls inside the metric unless the user explicitly wants judge-based evaluation.
• If the user needs LLM-as-judge scoring for a non-agent GEPA run, prefer a plain typed AxGen evaluator instead of writing a custom judge abstraction.
• maxMetricCalls must be large enough to cover the initial validation pass over validationExamples.
• GEPA optimizes generic string components exposed by getOptimizableComponents(). If a tree exposes no components, optimization will fail.
• Use held-out validation examples for selection. Do not reuse the training set as validationExamples.
• result.optimizedProgram is the easy-to-apply best candidate. result.paretoFront is the full trade-off set for multi-objective runs.
• Direct AxGEPA still has its own bootstrap option, but top-level optimize(...) composes the existing AxBootstrapFewShot optimizer before GEPA instead.