agentleFS
MacroMan5MacroMan5/autotrain-yolo/.claude/skills/explain-results/SKILL.md

explain-results

Skill8 starsChanged 8 months agoMITView on GitHub

Explain training results in plain English — translates metrics into actionable insights for any audience.

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 10 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If user specifies a path or experiment ID, use that

    line 14
  2. Distinctive:

    Read from the experiment directory:

    line 17
  3. Distinctive:

    If there is a baseline comparison, translate the delta: "Compared to our starting point, this run [improved/decreased] overall detection by …

    line 56
  4. Distinctive:

    Use plain language: "The model is strongest at detecting [class] — it correctly finds and outlines [X]% of them."

    line 62
  5. Very specific:

    When user requests --technical or asks for technical details, add these sections after the plain-English report:

    line 111
  6. Distinctive:

    If results.csv is available, analyze:

    line 119
  7. Very specific:

    If the user requests saving, or if the experiment has a clear ID, offer to save as experiments/explain_<exp_id>.md.

    line 133
  8. Distinctive:

    Keep it practical — no AI hype, no buzzwords

    line 137
  9. Distinctive:

    Use "the model" not "the AI" or "the neural network"

    line 138
  10. Distinctive:

    When in doubt, explain less and recommend more

    line 141
  11. Distinctive:

    Always ground quality judgments in the metrics-guide.md thresholds — don't invent your own scale

    line 142
  12. Distinctive:

    If data is missing (no results.csv, no per-class AP), say so plainly and skip that section rather than guessing

    line 143

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Explain Results

Translates YOLO training metrics into plain-English explanations. Two audience modes: non-technical (default) and technical.

Data

Find the experiment to explain:

  1. If user specifies a path or experiment ID, use that
  2. Otherwise, find the latest experiments/exp_NNN_* directory (highest NNN)

Read from the experiment directory:

  • report.md — experiment summary with metrics and deltas
  • metrics.yaml — structured metrics, per-class AP, overrides, config
  • train/results.csv or results.csv (if available) — epoch-by-epoch training log

Also read:

  • experiments/summary.md — for historical context (how this compares to other runs)
  • experiments/dataset_profile.yaml — for dataset size, class counts, image counts
  • Reference thresholds from skills/analyze-results/resources/metrics-guide.md

Report Structure

Generate a plain-English report with these sections:

1. What Happened

Summarize the training run in one paragraph a project manager could understand.

Template: "We trained a [model] for [X epochs] on [Y images] across [Z classes]. The training [completed normally / stopped early at epoch N / showed signs of overfitting]. This took approximately [time if available]."

Include what changed vs baseline if this is not the baseline run (e.g., "This run increased the image size from 640 to 1280 pixels").

2. How Good Is It

Translate the core metrics using analogies, not jargon. Use the metrics-guide.md thresholds to provide context.

QualitymAP50-95Plain English
Great>0.60"The model reliably finds and precisely locates objects — ready for production use"
Good0.45-0.60"The model catches most objects and places boxes reasonably well — solid for many applications"
Fair0.30-0.45"The model finds some objects but often misses or misplaces them — needs more work"
Poor<0.30"The model is still learning — not ready for real use yet"

Translate individual metrics:

  • Precision: "When the model says it found something, it's right X% of the time" (e.g., precision=0.85 -> "correctly identifies the object 85 out of 100 times it makes a detection")
  • Recall: "Out of all the objects actually present, the model finds X%" (e.g., recall=0.70 -> "catches 70 out of every 100 objects in the images")
  • mAP50: "How well it draws boxes around objects (at a forgiving threshold)" — use this to explain detection quality
  • mAP50-95: "The overall score — combines finding objects AND precisely outlining them"

If there is a baseline comparison, translate the delta: "Compared to our starting point, this run [improved/decreased] overall detection by [X points]. In practical terms, [concrete impact]."

3. What It's Best At

List the top-performing classes by per-class AP (from metrics.yaml per_class_ap).

Use plain language: "The model is strongest at detecting [class] — it correctly finds and outlines [X]% of them."

Group into tiers using metrics-guide.md per-class thresholds:

  • Nailed it (AP > 0.80): These classes are well-learned
  • Getting there (AP 0.60-0.80): Decent but room to improve
  • Needs work (AP 0.40-0.60): Struggling — likely needs more training data
  • Not yet (AP < 0.40): Severely underperforming

4. What It Struggles With

List the worst-performing classes and provide likely reasons:

  • Few training examples for that class (check dataset_profile.yaml for class distribution)
  • Small objects (if dataset profile shows small object prevalence)
  • Visual similarity to other classes
  • High intra-class variation

Frame constructively: "The model has the hardest time with [class] (finds only X out of 100). This is likely because [reason]. To improve this, [action]."

5. What to Do Next

Provide 1-3 actionable recommendations in plain language. No ML jargon.

Map common situations to advice:

SituationRecommendation
High precision, low recall"The model is cautious — it's accurate when it detects something, but misses too many objects. Adding more training images would help."
Low precision, high recall"The model is trigger-happy — it finds most objects but also flags things that aren't there. Adding more examples of empty backgrounds would help."
One class much worse than others"The model struggles with [class]. Collecting 50-100 more labeled examples of [class] would likely improve this."
Small objects missed"Small objects are being missed. Try training with larger image sizes (e.g., 1280 instead of 640) so the model can see fine details."
Overall metrics plateaued"The model has stopped improving with the current setup. Consider trying a different model architecture or adding more diverse training data."
Overfitting detected"The model memorized the training images instead of learning general patterns. Reduce training duration or add more variety to training images."

6. Key Numbers

A summary table for stakeholders — no jargon, just the essentials.

| Metric              | Value  | Rating    | What It Means                          |
|---------------------|--------|-----------|----------------------------------------|
| Overall Score       | 0.XX   | Good/Great| [one-line plain explanation]            |
| Detection Accuracy  | 0.XX   | ...       | "Right X% of the time it makes a call" |
| Object Coverage     | 0.XX   | ...       | "Finds X% of all objects"              |
| Best Class          | [name] | [AP]      | "Finds X% of [class] objects"          |
| Worst Class         | [name] | [AP]      | "Finds only X% of [class] objects"     |
| Training Duration   | N eps  | ...       | "Trained for N rounds"                 |

Technical Mode

When user requests --technical or asks for technical details, add these sections after the plain-English report:

Per-Class AP Breakdown

Full table of all classes with AP values, sorted descending. Include delta vs baseline if available.

Training Dynamics

If results.csv is available, analyze:

  • Convergence: How quickly did metrics improve? At what epoch did improvement slow?
  • Overfitting signals: Compare train loss vs val loss trends. Flag divergence.
  • Loss components: Which losses (box, cls, dfl) are dominant?
  • Learning rate: What schedule was used? Did it correlate with metric jumps?

Configuration Details

List all overrides, architecture config, and key hyperparameters.

Output

Print the report to the console.

If the user requests saving, or if the experiment has a clear ID, offer to save as experiments/explain_<exp_id>.md.

Guidelines

  • Keep it practical — no AI hype, no buzzwords
  • Use "the model" not "the AI" or "the neural network"
  • Percentages and fractions over decimal scores: "85 out of 100" not "0.85"
  • Frame struggles as opportunities: "needs more examples" not "fails at"
  • When in doubt, explain less and recommend more
  • Always ground quality judgments in the metrics-guide.md thresholds — don't invent your own scale
  • If data is missing (no results.csv, no per-class AP), say so plainly and skip that section rather than guessing

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.