Adds optuna-hpo skill for hyperparameter optimisation

AGENTS.md

@@ -7,6 +7,7 @@ These skills are:
  - hugging-face-evaluation-manager -> "hf_model_evaluation/skills/hugging-face-evaluation-manager/SKILL.md"
  - hugging-face-paper-publisher -> "hf-paper-publisher/skills/hugging-face-paper-publisher/SKILL.md"
  - model-trainer -> "hf-llm-trainer/skills/model-trainer/SKILL.md"
+ - optuna-hpo -> "hf-optuna-hpo/skills/optuna-hpo/SKILL.md"
 
 IMPORTANT: You MUST read the SKILL.md file whenever the description of the skills matches the user intent, or may help accomplish their task. 
 
@@ -16,6 +17,7 @@ hugging-face-dataset-creator: `Create and manage datasets on Hugging Face Hub. S
 hugging-face-evaluation-manager: `Add and manage evaluation results in Hugging Face model cards. Supports extracting eval tables from README content and importing scores from Artificial Analysis API. Works with the model-index metadata format.`
 hugging-face-paper-publisher: `Publish and manage research papers on Hugging Face Hub. Supports creating paper pages, linking papers to models/datasets, claiming authorship, and generating professional markdown-based research articles.`
 model-trainer: `This skill should be used when users want to train or fine-tune language models using TRL (Transformer Reinforcement Learning) on Hugging Face Jobs infrastructure. Covers SFT, DPO, GRPO and reward modeling training methods, plus GGUF conversion for local deployment. Includes guidance on the TRL Jobs package, UV scripts with PEP 723 format, dataset preparation and validation, hardware selection, cost estimation, Trackio monitoring, Hub authentication, and model persistence. Should be invoked for tasks involving cloud GPU training, GGUF conversion, or when users mention training on Hugging Face Jobs without local GPU setup.`
+optuna-hpo: `Hyperparameter optimisation for LLM fine-tuning using Optuna. Orchestrates distributed HPO studies with cloud GPU backends (HuggingFace Jobs, Modal, RunPod). Features include TPE sampling, MedianPruner for early stopping, configurable search spaces (learning rate, batch size, LoRA parameters), budget management, Hub persistence, and Gradio visualisation. Use when users want to tune hyperparameters for transformer fine-tuning, find optimal training configurations, or run HPO studies with cost constraints.`
 </available_skills>
 
 Paths referenced within SKILL folders are relative to that SKILL. For example the hf_dataset_creator `scripts/example.py` would be referenced as `hf_dataset_creator/scripts/example.py`. 

README.md

@@ -72,6 +72,7 @@ This repository contains a few skills to get you started. You can also contribut
 | `hf_dataset_creator/`   | Prompts, templates, and scripts for creating structured training datasets. | [SKILL.md](hf_dataset_creator/skills/hugging-face-dataset-creator/SKILL.md) |
 | `hf_model_evaluation/`  | Instructions plus utilities for orchestrating evaluation jobs, generating reports, and mapping metrics. | [SKILL.md](hf_model_evaluation/skills/hugging-face-evaluation-manager/SKILL.md) |
 | `hf-llm-trainer/`       | Comprehensive training skill with `SKILL.md` guidance, helper scripts (e.g., `train_sft_example.py`, `convert_to_gguf.py`, cost estimators). | [SKILL.md](hf-llm-trainer/skills/model-trainer/SKILL.md) |
+| `hf-optuna-hpo/`        | Hyperparameter optimisation for LLM fine-tuning using Optuna. Orchestrates distributed HPO studies with cloud GPU backends, budget management, and Gradio visualisation. | [SKILL.md](hf-optuna-hpo/skills/optuna-hpo/SKILL.md) |
 | `hf-paper-publisher/`   | Tools for publishing and managing research papers on Hugging Face Hub. Index papers from arXiv, link papers to models/datasets, generate professional research articles from templates, and manage paper authorship. | [SKILL.md](hf-paper-publisher/skills/hugging-face-paper-publisher/SKILL.md) |
 
 ### Using skills in your coding agent
@@ -82,6 +83,7 @@ Once a skill is installed, mention it directly while giving your coding agent in
 - "Use the HF model evaluation skill to launch `run_eval_job.py` on the latest checkpoint."
 - "Use the HF dataset creator skill to draft new few-shot classification templates."
 - "Use the HF paper publisher skill to index my arXiv paper and link it to my model."
+- "Use the Optuna HPO skill to find optimal learning rate and LoRA parameters for my fine-tuning job."
 
 Your coding agent automatically loads the corresponding `SKILL.md` instructions and helper scripts while it completes the task.
 

hf-optuna-hpo/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "optuna-hpo",
+  "version": "1.0.0",
+  "description": "Hyperparameter optimisation for LLM fine-tuning using Optuna. Orchestrates distributed trials across cloud backends (Huggingface Jobs, Modal &c.) with intelligent sampling, early stopping and cost tracking. Train the future without going broke.",
+  "author": {
+    "name": "Chris von Csefalvay"
+  },
+  "repository": "https://github.com/huggingface/skills",
+  "license": "Apache-2.0",
+  "keywords": [
+    "huggingface",
+    "optuna",
+    "hyperparameter",
+    "optimisation",
+    "hpo",
+    "fine-tuning",
+    "llm",
+    "trl",
+    "distributed",
+    "cloud"
+  ]
+}