Skip to main content
skill CX Codex

yolo-training — Claude Code skill: what it does, how to install

yolo-training reads YOLO26 training curves and results.csv, diagnoses overfitting or poor mAP, and points to the cheapest fix first.

Apache-2.0 ★ 1,216 updated 2026-10-24

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install ultralytics-dev@claude-settings
Open on GitHub

What yolo-training does

The skill inspects results.csv and the confusion matrix from a YOLO26 run across detect, segment, pose, obb, classify and depth, and works out whether the issue is undertraining, a train/val gap, weak localization versus weak recall, or an uneven class spread. Fixes are ordered by how cheap they are to test, not by expected payoff: epochs and schedule first, then augmentation, loss weights and LR, model size, resolution, and data quality last.

It ships a table mapping curve patterns to likely causes, plus a list of defaults that quietly break run comparisons. optimizer=auto ignores a manually set lr0 unless the optimizer is switched to AdamW or SGD first. nbs=64 means dropping batch size from 64 to 16 barely changes the effective gradient step. close_mosaic=10 produces a late-epoch mAP jump that looks like convergence but isn't. For detection, the early-stopping criterion is mAP50-95 alone, so precision and recall trends don't factor in.

There's no dataset-analysis tooling bundled, so auditing label quality means writing your own script and eyeballing images. references/diagnostics.md lists causes and knobs per pattern, references/task-notes.md covers task-specific quirks.

What it helps with

  • read a results.csv to decide when to stop training
  • tell overfitting apart from underfitting from train/val curves
  • explain why AP50 looks fine but AP50-95 is weak
  • choose between adjusting learning rate, augmentation, or model size
  • figure out a late-epoch mAP jump in a YOLO26 run

Example prompts for the agent

  • Read my results.csv and tell me why mAP50-95 stalled
  • Why is val loss climbing while train loss keeps dropping on this pose model
  • Should I scale up the model or change augmentations here

How to install yolo-training

1Plugin marketplace

/plugin marketplace add fcakyon/claude-codex-settings
/plugin install ultralytics-dev@claude-settings

This installs the whole ultralytics-dev plugin with all its skills

2Skills CLI (Vercel)

npx skills add fcakyon/claude-codex-settings --skill yolo-training -a claude-code

3Manually: put the files in place

~/.claude/skills/yolo-training/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/yolo-training/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about yolo-training

How do I install yolo-training in Claude Code?

Run /plugin marketplace add fcakyon/claude-codex-settings, then /plugin install ultralytics-dev@claude-settings.

What does yolo-training do?

It reads YOLO26 training curves and results.csv, works out why mAP is low or the model is overfitting, and recommends which training parameter to adjust, starting with the cheapest to test.

Why does changing the learning rate on YOLO26 sometimes have no effect?

The default optimizer=auto picks MuSGD or AdamW on its own and ignores a manually set lr0 unless the optimizer is explicitly switched to AdamW or SGD.

Source text

SKILL.md · Apache-2.0
---
name: yolo-training
description: This skill should be used when user asks to "improve my mAP", "why is my model overfitting", "my training is diverging", "read my results.csv", "interpret my training curves", "my AP50 is good but AP50-95 is bad", "my recall is low", "how do I pick learning rate", "which augmentations should I use", "should I use a bigger model", "tune hyperparameters", or asks how to train YOLO26 for detection, instance or semantic segmentation, pose, OBB, classification, or depth.
---

# YOLO26 training

Read the run before changing anything. The `results.csv` and confusion matrix usually name the
problem already.

## Order of operations

Ordered by cost to try, cheapest first, not by size of the potential win.

1. **Epochs and schedule.** Undertrained looks like every other problem, and it costs nothing
   but time to rule out.
2. **Augmentation.** The knob for the generalization gap, at no extra compute per epoch.
3. **Loss weights and LR.** Cheap, and the curves usually say which one is wrong.
4. **Model size.** Scale up when train loss is still falling at the end of the schedule and the
   train and val curves sit close together. That is underfitting, and it is the only case a
   bigger model reliably fixes.
5. **Resolution.** Compute scales with the square of `imgsz`, so 640 to 1280 is roughly 4x the
   training budget, and pretrained weights transfer worse the further you move from the size
   they were fit at. Justify it with the object sizes in your data, not as a default first move.
6. **Data**, label quality and class balance. The highest ceiling and the slowest to move. The
   package ships no dataset-analysis tooling, so any audit here is your own script plus looking
   at images. Worth it once the cheap knobs are spent.

## Diagnostic loop

```python
import pandas as pd

df = pd.read_csv("runs/detect/train/results.csv")
df.columns = df.columns.str.strip()
print(df.tail(10)[["epoch", "train/box_loss", "val/box_loss", "metrics/mAP50(B)", "metrics/mAP50-95(B)"]])
print("best epoch:", df["metrics/mAP50-95(B)"].idxmax(), "of", len(df))
```

Then read, in this order:

| Read                                       | Question it answers                       |
| ------------------------------------------ | ----------------------------------------- |
| best epoch vs total epochs                 | undertrained, overtrained, or right       |
| train loss vs val loss trend               | which side of the generalization gap      |
| mAP50 vs mAP50-95                          | classification and recall vs localization |
| P vs R at the operating point              | over-suppression vs over-firing           |
| per-class AP spread                        | one broken class or a general weakness    |
| confusion matrix background row and column | false positives vs missed detections      |

`references/diagnostics.md` maps each pattern to a cause and a knob, and lists what to rule
out before turning that knob. Read it before recommending a change.
`references/task-notes.md` covers detect, segment, semantic, pose, obb, classify, and depth
specifics.

## Defaults that will surprise you

These produce "I changed X and nothing happened". All six are current defaults.

1. **`optimizer=auto` ignores `lr0` and `momentum`.** It is the default. It picks `MuSGD` at
   lr 0.01 when `ceil(len(dataset) / max(batch, nbs)) * epochs` exceeds 10000, otherwise `AdamW`
   at `0.002 * 5 / (4 + nc)`, and forces `warmup_bias_lr=0`. Crossing that iteration count
   silently changes optimizer between two runs you meant to compare. Setting `lr0` while leaving
   `optimizer=auto` does nothing. Set `optimizer=AdamW` or `optimizer=SGD` explicitly first.
2. **`nbs=64` normalizes the loss, so batch does not scale LR the way you assume.** Below 64 the
   trainer accumulates gradients to an effective 64. Dropping batch 64 to 16 changes almost
   nothing about the effective step.
3. **`close_mosaic=10` turns off mosaic for the last 10 epochs.** The late jump in mAP is that
   switch, not convergence. On a 20-epoch run it is half the schedule, and on a 10-epoch run
   mosaic never runs at all.
4. **Fitness for detect is mAP50-95 alone**, weights `[0, 0, 0, 1]`. `best.pt` and `patience`
   ignore precision, recall, and mAP50 completely. Segment and pose sum both heads, classify
   uses `(top1 + top5) / 2`, semantic uses mIoU. A run whose precision is climbing while
   mAP50-95 is flat will still early-stop.
5. **`max_det=300`** truncates validation on dense scenes. Above roughly 300 objects per image
   your recall ceiling is an artifact.
6. **YOLO26 `end2end` models decode without NMS**, so `iou` does nothing on them. `agnostic_nms`
   still applies, the predictor passes it into the head, so only the IoU threshold is dead.

## Starting recipe

Fine-tuning a pretrained checkpoint on a normal custom dataset:

```bash
yolo train model=yolo26s.pt data=my-data.yaml epochs=200 imgsz=640 batch=16 \
  optimizer=AdamW lr0=0.001 lrf=0.01 cos_lr=True warmup_epochs=3 \
  patience=50 close_mosaic=20
```

Deviate on evidence from the charts, one axis at a time. It differs from the shipped defaults
because `epochs=100` is short for a small dataset, `patience=100` never fires inside 100 epochs,
and `close_mosaic=10` is too short a clean tail once epochs rise.

Change one thing per run and keep `seed` fixed. Run-to-run noise on a small dataset is often
0.5 to 1.0 mAP, so a 0.3 mAP "improvement" from a single run is not a result. Confirm anything
under about 1 point across three seeds.

© Fatih C. Akyon · Apache-2.0 · fcakyon/claude-codex-settings

Similar skills

All skills for AI and ML →

From the same set113

The whole set →
commit-creator commit-creator reviews staged changes, plans a single commit or a logical series, and writes concise commit messages. Available for Claude Code and Codex. CX Codex ★ 1,216repo stars site-architecture The site-architecture skill for Claude Code and Codex plans or restructures site structure, including page hierarchy, navigation, URL patterns, breadcrumbs, and internal links. CX Codex +1 ★ 1,216repo stars derive-client derive-client records browser network traffic into a HAR archive and turns captured internal endpoints into a standalone API client or CLI script. CX Codex +1 ★ 1,216repo stars polar-local-environment The polar-local-environment skill for Claude Code manages Polar’s local Docker setup, including stack operations, service debugging, and separate environments for multiple worktrees. CX Codex +1 ★ 1,216repo stars supabase-cli Equips coding agents to run Supabase CLI commands for local environments, schema migrations, edge function deployments, and TypeScript type generation. CX Codex +1 ★ 1,216repo stars payment-testing The payment-testing rule explains local checks for login, Stripe events, subscription renewals, refunds, and the backoffice. Use it when a payment flow behaves differently in your local stack. CX Codex +1 ★ 1,216repo stars troubleshooting troubleshooting — a rule covering common failures in a Dockerized Polar dev stack, from stuck ports to stale database connections. CX Codex +1 ★ 1,216repo stars supabase-js Adds practical cheat sheets and patterns for @supabase/supabase-js to your AI coding agent, covering Auth, Storage, Edge Functions, and queries. CX Codex +1 ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open