@damiangilgonzalez/harness 1.3.7

package/skills/unslop/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: unslop
+description: "Use when a written text must be audited against a named catalogue of AI tells before it ships: puffery, `not just X but Y`, the rule of three, em dashes, filler, hedging, abstract metaphor nouns. Names each hit and fixes it. NOT the register rewrite in the user's own voice (that is `bro`), NOT a reusable voice guide (that is `brand-voice`)."
+tags: [unslop, ai-tells, editing, audit, slop, publish-check, revisar-texto]
+recommends: [bro, brand-voice, technical-writing]
+profiles: [minimal, core, ui, full]
+origin: risco
+---
+
+# unslop: the named-tell audit a text passes before it ships
+
+`bro` decides how a text should *sound*. This decides whether a text still carries the marks of a
+machine, tell by named tell, on the words that are actually there. Run it on anything about to leave
+the session: a README, a post, an email, a landing page, a commit body.
+
+## The pass
+
+1. **Scan against the tables below.** Every hit gets located, not sensed. If you cannot name the
+   tell, it is not a finding.
+2. **Rewrite in place.** Preserve meaning, facts, numbers, links, commitments and the intended tone.
+3. **Restore the voice** (next section). A text stripped of tells and nothing else reads as sterile,
+   which is its own tell.
+4. **Self-audit once more.** Ask: what still makes this obviously machine written? Fix that too.
+5. **Return the text.** On request, return the list of named hits alongside it.
+
+## Removing tells is half the job
+
+Voiceless writing is as obvious as slopped writing. After the cuts, put something back:
+
+- **Have an opinion.** React to the facts instead of listing balanced pros and cons.
+- **Vary the rhythm.** Short sentence. Then a longer one that takes its time and earns the length.
+- **Admit complexity.** "Impressive and slightly unsettling" beats "impressive".
+- **Use "I" when it fits.** First person is not unprofessional.
+- **Allow some mess.** Perfect symmetry looks manufactured.
+- **Be specific.** Not "this is concerning" but "it churns for six hours at 3am and nobody is watching".
+
+## Content tells
+
+| Tell | Fix |
+| --- | --- |
+| Puffery: "pivotal moment", "testament to", "evolving landscape", "indelible mark" | State what happened |
+| Name dropping outlets with no context | Pick one, quote what it said |
+| Decorative `-ing` clauses: "highlighting...", "ensuring...", "showcasing..." | Delete, or expand into a real claim with a source |
+| Promotional adjectives: "nestled", "vibrant", "breathtaking", "renowned", "must-visit" | Neutral description |
+| Vague attribution: "experts believe", "reports suggest", "critics argue" | Name the source or cut the claim |
+| The formulaic challenge arc: "despite challenges, X continues to thrive" | Specific facts instead of the arc |
+
+## Language tells
+
+| Tell | Fix |
+| --- | --- |
+| AI vocabulary: additionally, crucial, delve, enhance, foster, garner, interplay, intricate, landscape, pivotal, showcase, tapestry, testament, underscore, vibrant | The plain word |
+| Fancy ways to say "is": "serves as", "stands as", "boasts", "features" | "is", "has" |
+| "Not just X, but Y" | State the point directly |
+| Rule of three: forcing every list into three items | The number the facts have |
+| Synonym cycling: protagonist, main character, central figure, hero in one paragraph | Pick one and repeat it |
+| False ranges: "from X to Y" where X and Y share no scale | List the items |
+| Abstract metaphor nouns: substrate, wedge, vector, locus, nexus, primitive, surface, bedrock, scaffolding, paradigm, flywheel, north star, gold-plating, ratchet, evacuate | The concrete word: base, add, way, more than the job needs, move out |
+
+## Style and punctuation tells
+
+| Tell | Fix |
+| --- | --- |
+| Em dashes, anywhere | End the sentence, or use a comma. Swapping in parentheses trades one tell for another |
+| Colons as mid-sentence connectors | Let the point stand as its own sentence. Colons are for lists and examples |
+| Bold on every proper noun and acronym | Bold what the reader must not miss, nothing else |
+| Inline-header lists whose bold label restates the line: "**Performance:** performance improved" | Prose. A bold lead-in that ends in a period and is followed by genuinely new detail is fine |
+| Title Case Headings | Sentence case |
+| Decorative emoji in headings and bullets | Remove |
+| Curly quotes | Straight quotes |
+
+## Filler, hedging and plain speech
+
+| Tell | Fix |
+| --- | --- |
+| "In order to", "due to the fact that", "it is important to note that" | "To", "because", delete |
+| Stacked hedges: "could potentially possibly be argued that it might" | "may", or the claim itself |
+| Generic conclusion: "the future looks bright" | A specific plan, date or number |
+| Chatbot phrases: "I hope this helps", "let me know if", "certainly", "great question" | Remove |
+| Cutoff disclaimers: "while specific details are limited" | Find the detail or drop the sentence |
+| Sycophancy: "you're absolutely right" | Answer directly |
+| Feeling instead of mechanism: "the database stays close at hand" | The mechanism or the number: "`.toSQL()` returns the exact string sent to the database" |
+| A sentence that would fit unchanged in another project's docs | Cut it. It says nothing about this one |
+| Dense sentences the reader has to reparse | One idea per sentence |
+| Passive with a hidden actor: "queries are validated" | Name the actor: "the compiler validates queries" |
+| Adverbs propping up weak verbs: "runs quickly", "significantly improves" | A stronger verb or the measured number |
+| Fancy synonyms: utilize, leverage, facilitate, numerous, in the event that | use, use, help, many, if |
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do this instead |
+| --- | --- | --- |
+| Report the tells and leave the text unfixed | The user asked for a clean text, not a diagnosis | Fix in place, list on request |
+| Cut every tell and stop | Sterile prose is the other AI tell | Restore opinion, rhythm and specifics |
+| Rewrite the meaning while cleaning the style | The edit silently changes the claim | Facts, numbers, links and commitments stay exact |
+| Strip a term because it sounds technical | Precision lost to style is a defect | Keep the term, explain it once |
+| Touch code, commands, URLs, quotes or regulated wording | Those are not prose | Leave them byte for byte |
+| Claim the result will pass an AI detector | Nobody can promise that | Promise named tells removed, nothing more |
+| Flatten a voice the author chose on purpose | Some authors do write long, warm or formal | Match the intended tone, cut only the machine marks |
+
+## Output boundary
+
+Return the cleaned text as an artifact, with no preface. Keep harness commentary, the findings list
+and any compass block clearly outside it, so nothing that is not the text can be copied into an
+email or a document by accident.
+
+## Where this ends
+
+- **`bro`** owns the register pass: make it sound like a person, in the user's language, fitted to the
+  channel and the relationship. A bare "bro" after an answer is always `bro`. This skill is the named
+  audit of a text that already exists, before it goes out.
+- **`brand-voice`** owns the standing voice system across writers and channels.
+- **`technical-writing`** owns structure: what belongs in a tutorial, a reference, a README.
+- **`landing-copy`** owns conversion architecture. Clean its words only after it has chosen them.

package/skills/unslop/evals/README.md

@@ -0,0 +1,25 @@
+# Evals — unslop
+
+The claim under test is the boundary as much as the capability. `bro` sits directly next to this
+skill in the base install, and a description that blurs them costs every user two owners for one
+turn. Half the negatives here exist to prove the split holds.
+
+## Triggering
+
+Load only `unslop` and run every prompt in 3–5 fresh sessions. A positive passes when `unslop` loads
+in a majority of trials; a negative passes when it stays quiet and the declared `route_to` skill is
+the real owner. Require at least 90% accuracy, and treat any failure on the two `bro` negatives as
+blocking rather than statistical: those are the cases the split was designed for.
+
+Run the mirror direction too. `bro`'s own suite carries a negative that routes here; both must pass
+in the same round, or the boundary only exists on one side.
+
+## Capability
+
+Run the scenario without the skill and with it, same post and one grader, three trials. The
+with-skill condition must satisfy at least 80% of the rubric and beat the baseline by at least 20
+percentage points.
+
+Two points discriminate hardest: **naming** the tells by category (a baseline rewrites silently) and
+**preserving** the code block, the price and the URLs (a baseline edits them while tidying). Grade
+both strictly.

package/skills/unslop/evals/cases.yaml

@@ -0,0 +1,60 @@
+skill: unslop
+
+# `unslop` is the named-tell audit of a text that already exists, run before it
+# ships. `bro` is the register pass: sound like a person, in the user's language,
+# fitted to the channel. A bare "bro" is always `bro`; "check this for AI tells
+# before I publish it" is always this skill.
+should_trigger:
+  - prompt: "Revisa este README antes de publicarlo y quítale todo lo que huela a IA."
+    why: "A pre-publication audit of an existing text is the exact contract, in the user's own words."
+
+  - prompt: "Unslop this."
+    why: "The bare skill name over a text in context is the shortest form of the request."
+
+  - prompt: "Can you go through this post and tell me which bits read as AI-written, then fix them?"
+    why: "Named findings plus a fix is what distinguishes this from a general tone rewrite."
+
+  - prompt: "Este texto está lleno de guiones largos y de 'no solo X, sino Y'. Límpialo."
+    why: "The user names two catalogued tells outright; the fix is the enumerated pass."
+
+  - prompt: "I keep getting told my docs sound like ChatGPT wrote them. What exactly am I doing?"
+    why: "The user wants the tells named, which no other writing skill in the catalog does."
+
+  - prompt: "Before this goes to the client, strip the puffery and the hedging but keep every number exact."
+    why: "A ship gate over existing prose with a preserve-the-facts constraint."
+
+should_not_trigger:
+  - prompt: "Bro."
+    route_to: "bro"
+    why: "A bare bro after an answer is the register pass over the last message, not an audit of a supplied text."
+
+  - prompt: "Haz que este correo suene más cercano y menos formal para un cliente de confianza."
+    route_to: "bro"
+    why: "Choosing a warmer register for a specific relationship is bro's job; no tell is being audited."
+
+  - prompt: "Define how our company should sound across the blog, support replies and job ads."
+    route_to: "brand-voice"
+    why: "A standing voice system across channels is brand-voice, not a one-text audit."
+
+  - prompt: "Split this mixed README into a tutorial and an API reference with runnable examples."
+    route_to: "technical-writing"
+    why: "Document structure is technical-writing; unslop edits words, it does not decide document modes."
+
+  - prompt: "Write the hero headline, the offer and the CTA for our pricing page."
+    route_to: "landing-copy"
+    why: "Conversion architecture and net-new copy belong to landing-copy; the audit comes after."
+
+  - prompt: "Translate this announcement into Catalan and adapt the date formats."
+    route_to: "translation-l10n"
+    why: "Translation and locale adaptation are owned elsewhere, even though good prose matters there too."
+
+capability:
+  - scenario: "A 400-word product-launch blog post that opens with 'In today's rapidly evolving landscape', uses four em dashes, three bold-label bullets whose labels restate their lines, 'not just faster, but smarter', 'experts agree', two stacked hedges, and closes with 'the future looks bright'. It also contains a code block, a pricing figure of EUR 39/month and two URLs."
+    must_include:
+      - "names the tells it found by category rather than reporting a general impression"
+      - "removes every em dash without substituting parentheses or en dashes"
+      - "converts the bold-label bullets whose label restates the line into prose, and leaves any bold lead-in that adds new detail"
+      - "replaces 'experts agree' with a named source or cuts the claim"
+      - "keeps the code block, the EUR 39/month figure and both URLs byte for byte"
+      - "leaves the text with a voice: at least one specific, opinionated sentence rather than sterile neutrality"
+      - "returns the cleaned text as the artifact, with the findings list kept outside it"

package/skills/unsloth/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: unsloth
+description: "Use when fine-tuning an open-weight LLM fast on ONE GPU with low VRAM — Unsloth's fast model loaders with 4-bit QLoRA and the trl trainer, response-only loss masking so the prompt is not trained on, GRPO reasoning fine-tunes, and export to merged 16-bit, GGUF or the Hub. NOT whether, why or which method to fine-tune (that is `finetuning`), NOT running the exported GGUF locally (that is `ollama`), NOT serving-engine flags and throughput (that is `vllm`), NOT building the JSONL dataset (that is `training-data`)."
+tags: [unsloth, qlora, lora, single-gpu, gguf, fine-tuning]
+recommends: [finetuning, training-data, open-weights, ollama, huggingface]
+origin: risco
+---
+
+# Unsloth — fast, low-VRAM fine-tuning on one GPU
+
+Unsloth is a fine-tuning *backend*: hand-written Triton kernels + a patched LoRA/QLoRA path that make
+`transformers` + `trl` training run faster and fit a much bigger model on a single consumer GPU. You
+reach for it when the *decision to fine-tune is already made* and the problem is now "make this run on
+the one GPU I have." This skill owns the backend + the export mechanics. It does **not** decide
+whether fine-tuning is even the right move (`finetuning`), and it does **not** run the model you
+export (`ollama` / `vllm`).
+
+## Read this first (the two things that bite everyone)
+
+1. **Single-GPU is the free-tier assumption.** The open (Apache-2.0) core is built for one GPU.
+   Multi-GPU / multi-node "works but a better version is coming" per the docs, and the polished
+   multi-GPU + full-finetuning path is gated behind the paid Pro/Enterprise tiers — **verify the
+   current split at docs.unsloth.ai before you promise anyone `torchrun --nproc 8`.** If the plan is
+   truly multi-node from day one, that is an `axolotl`/native-`trl`/`accelerate` job, not this.
+2. **You must mask the prompt or your loss is wrong.** Fine-tuning a chat model means computing loss
+   on the *assistant* turn only. Use Unsloth's `get_chat_template` for the format and
+   `train_on_responses_only` for the mask. Skip it and the model trains on predicting the user's
+   words too — loss looks fine, behaviour is subtly broken (and on some templates you hit a
+   zero-loss trap). This is the single most common mistake; it is section 4 for a reason.
+
+### Version / performance reality (fast-moving — verify at author time)
+
+The headline, straight off docs.unsloth.ai (accessed 2026-07): **~2x faster training with ~70% less
+VRAM, no accuracy loss**, on a single GPU with the free core. Treat that as a *class* of improvement,
+not a contract:
+
+- The baseline is a **standard Hugging Face + FlashAttention-2 QLoRA** pipeline, not "raw PyTorch."
+- Numbers are **model-, GPU-, and config-specific.** Some pages/reviews cite ~60% VRAM; GRPO/RL
+  claims ~80% less VRAM; MoE (e.g. gpt-oss, Qwen3-family MoE) shows much larger multipliers on
+  specific hardware (up to ~7–12x on a B200 in Unsloth's own MoE post). **Do not quote a single
+  number as gospel — cite the docs page you read and hedge.**
+- Licensing/pricing also moves: core is Apache-2.0 and free; a paid Pro tier and an Enterprise
+  (contact-sales) tier add multi-GPU/multi-node, full-parameter training, and faster kernels. **Check
+  unsloth.ai/pricing for the live tiers and figures.**
+
+### Setup
+
+Notebook-centric by design — the fastest path is one of the maintained Colab/Kaggle notebooks
+(`unslothai/notebooks`). Locally:
+
+```bash
+pip install unsloth            # pulls unsloth + unsloth_zoo; expects a recent PyTorch + CUDA
+python -c "import unsloth; print(unsloth.__version__)"
+```
+
+NVIDIA is the first-class target (min ~CUDA-capable GPU, works down to ~a free-Colab T4 for small
+models). AMD (ROCm) and Intel GPU support have landed as install targets — **verify your hardware on
+the docs' requirements page before assuming it works.** Don't pin a brittle version in your head;
+`unsloth` ships frequently — install fresh and read its startup banner (it prints the versions it
+patched).
+
+## Supported models (verify the live list)
+
+Unsloth advertises **500+ models** across text, vision, and TTS/embeddings. Families you can expect
+(confirm the specific checkpoint at docs.unsloth.ai/models — new releases land within days):
+
+- **Text:** Llama, Qwen, Gemma, Mistral/Mixtral, Phi, DeepSeek, GLM, and **gpt-oss** (OpenAI's
+  open-weight MoE).
+- **Vision (VLM):** e.g. Qwen-VL, Gemma vision, Llama-vision — via `FastVisionModel`.
+- Plus TTS and embedding fine-tunes in the notebook zoo.
+
+Prefer Unsloth's **pre-quantized 4-bit repos** (`unsloth/<model>-unsloth-bnb-4bit`) — faster download,
+fewer OOMs. Which base model + **which license** is right for you is an `open-weights` question, not
+this one: **never assert a model's license from memory** (Llama = Meta Community license, Gemma =
+custom terms, gpt-oss/Qwen vary by size) — read the model card.
+
+## Canonical flow
+
+Three steps: **load 4-bit → attach LoRA → SFTTrainer**. `FastModel` is the newer unified loader (text
++ vision); `FastLanguageModel` is the text path and still owns `.get_peft_model`.
+
+```python
+from unsloth import FastLanguageModel
+import torch
+from trl import SFTTrainer, SFTConfig
+from datasets import load_dataset
+
+max_seq_length = 2048  # Unsloth does RoPE scaling internally — pick what you need
+
+# 1) Load a (pre-quantized) base in 4-bit. This is the QLoRA memory win.
+model, tokenizer = FastLanguageModel.from_pretrained(
+    model_name    = "unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit",  # verify current id
+    max_seq_length= max_seq_length,
+    load_in_4bit  = True,   # QLoRA. False + load_in_16bit=True => 16-bit LoRA
+    # load_in_8bit / load_in_16bit / full_finetuning are the other switches
+    # token = "hf_...",     # only for gated repos
+)
+
+# 2) Attach LoRA adapters — you train ~1% of weights.
+model = FastLanguageModel.get_peft_model(
+    model,
+    r = 16,                 # rank: 8/16/32; higher = more capacity, more VRAM
+    lora_alpha = 16,        # a common default is alpha == r (some recipes use 2*r)
+    target_modules = ["q_proj","k_proj","v_proj","o_proj",
+                      "gate_proj","up_proj","down_proj"],
+    lora_dropout = 0,       # 0 is the optimized path
+    bias = "none",          # "none" is the optimized path
+    use_gradient_checkpointing = "unsloth",  # "unsloth" = ~30% less VRAM, fits longer context
+    random_state = 3407,
+)
+
+# 3) Train with trl's SFTTrainer (see section 4 before you call .train()).
+dataset = load_dataset("json", data_files="train.jsonl", split="train")  # your data
+trainer = SFTTrainer(
+    model = model, tokenizer = tokenizer, train_dataset = dataset,
+    args = SFTConfig(
+        max_seq_length = max_seq_length,
+        per_device_train_batch_size = 2,
+        gradient_accumulation_steps = 4,     # effective batch = 2*4
+        warmup_steps = 10,
+        max_steps = 60,                       # or num_train_epochs = 1
+        learning_rate = 2e-4,
+        logging_steps = 1,
+        optim = "adamw_8bit",                 # 8-bit optimizer = more VRAM saved
+        output_dir = "outputs",
+        seed = 3407,
+    ),
+)
+trainer.train()
+```
+
+MoE caveat: 4-bit QLoRA is **not** supported for MoE models yet — load MoE in 16-bit and LoRA the
+`gate_up_proj` / `down_proj` layers. (`load_in_4bit=False` for gpt-oss/Qwen3-MoE.) Verify on
+docs.unsloth.ai/basics/faster-moe.
+
+## Chat templates + response-only loss (do not skip)
+
+Format with Unsloth's template helper — **not** a hand-written string — so the special tokens match
+what the base model was trained on:
+
+```python
+from unsloth.chat_templates import get_chat_template
+
+tokenizer = get_chat_template(tokenizer, chat_template = "llama-3.1")  # match your base model
+# then map your messages -> a "text" column via tokenizer.apply_chat_template(...)
+```
+
+Then wrap the trainer so **loss is computed on the assistant turn only**:
+
+```python
+from unsloth.chat_templates import train_on_responses_only
+
+trainer = train_on_responses_only(
+    trainer,
+    instruction_part = "<|start_header_id|>user<|end_header_id|>\n\n",       # Llama-3
+    response_part    = "<|start_header_id|>assistant<|end_header_id|>\n\n",
+)
+# Gemma-3 would use: instruction_part="<start_of_turn>user\n", response_part="<start_of_turn>model\n"
+```
+
+The `instruction_part` / `response_part` strings are the **template's own turn markers** — they must
+match the chat template you applied, per model. Verify the mask worked before spending GPU-hours:
+
+```python
+# labels are -100 where masked. Decoding the non-masked tokens should show ONLY the answer.
+print(tokenizer.decode(trainer.train_dataset[0]["input_ids"]))
+print(tokenizer.decode([tokenizer.pad_token_id if x == -100 else x
+                        for x in trainer.train_dataset[0]["labels"]]))
+```
+
+More templates, thinking-mode (`enable_thinking`), and the vision path are in
+[references/masking-and-templates.md](references/masking-and-templates.md).
+
+## GRPO / reasoning fine-tuning (brief)
+
+Unsloth supports RL (GRPO and variants) with the same low-VRAM story — it plugs into `trl`'s
+`GRPOTrainer` / `GRPOConfig` and can use a built-in vLLM engine (`fast_inference=True`) for the
+rollout generation. Instead of imitating a target string, GRPO optimizes **reward functions** you
+write (e.g. "answer matches ground truth", "output obeys the `<reasoning>/<answer>` format"). The docs
+cite ~80% less VRAM for GRPO vs a standard setup — verify. This is how you turn a base model into a
+reasoning model on one GPU. The *choice* of SFT vs DPO vs GRPO is a `finetuning` decision; the
+mechanics + a runnable GSM8K reward example live in [references/grpo.md](references/grpo.md).
+
+## Export (the other half of this skill)
+
+After `trainer.train()` you have LoRA adapters. Pick an export by where it's going:
+
+```python
+# A) Merge LoRA into the base at 16-bit — the portable, high-quality artifact (vLLM, re-hosting).
+model.save_pretrained_merged("model_16bit", tokenizer, save_method = "merged_16bit")
+model.push_to_hub_merged("user/model", tokenizer, save_method = "merged_16bit", token = "hf_...")
+
+# B) Keep just the adapters (small, hot-swappable).
+model.save_pretrained_merged("model_lora", tokenizer, save_method = "lora")
+
+# C) GGUF for llama.cpp / Ollama — choose the quant that trades size vs quality.
+model.save_pretrained_gguf("model_gguf", tokenizer, quantization_method = "q4_k_m")
+model.push_to_hub_gguf("user/model-gguf", tokenizer,
+                       quantization_method = ["q4_k_m", "q8_0", "f16"], token = "hf_...")
+```
+
+Then **running** the GGUF is an `ollama` job (`ollama create` from the file, `ollama run`), and
+serving the merged-16bit at scale is a `vllm` job. Quant guidance: **Q4_K_M** is the everyday
+size/quality sweet spot, **Q8_0** near-lossless, **f16** the unquantized ceiling — lower quant = smaller
++ faster but real quality loss. Do **not** merge to 4-bit as your keeper artifact (quality drops;
+it's a niche path). Full export matrix + the Ollama/llama.cpp handoff:
+[references/export.md](references/export.md).
+
+## Guardrails / gotchas
+
+- **Single-GPU assumption (OSS).** Don't design a multi-node run on the free core; verify the paid
+  multi-GPU/multi-node status at docs.unsloth.ai first. `CUDA_VISIBLE_DEVICES` to one GPU if unsure.
+- **No mask = wrong training.** Without `train_on_responses_only`, loss covers the prompt; some
+  templates then show ~0 loss. Always decode-check the labels once.
+- **Wrong chat template = garbage.** The `chat_template` and the mask's `instruction_part`/
+  `response_part` must match the *base model's* markers. Use `get_chat_template`; never hand-roll.
+- **MoE ≠ 4-bit yet.** Load MoE models in 16-bit; QLoRA-4bit is unsupported for them (verify).
+- **GGUF quant is lossy.** Q4_K_M for size, Q8_0/f16 when quality matters. Merged-4bit is discouraged.
+- **`import unsloth` first.** Import it before `transformers`/`trl` so its patches apply; heed the
+  startup banner that prints patched versions.
+- **Numbers drift.** The 2x/70% headline is a *class*, not a guarantee — cite the docs page and hedge.
+
+## Related skills
+
+- **`finetuning`** — the method layer: FT-vs-RAG-vs-prompt, SFT/DPO/GRPO choice, hyperparameters, the
+  backend-agnostic `trl`/`peft` theory. Unsloth is *one fast backend* under it; go there for "should
+  I / how much / which method." This skill is "make it run on my GPU."
+- **`training-data`** — build the JSONL messages / preference pairs you feed the trainer. Data shape
+  and quality live there; this skill assumes you already have a dataset.
+- **`open-weights`** — choose the base model + read its license/size tradeoffs before you fine-tune.
+- **`ollama`** — run the GGUF you export, on one box. Export here, run there.
+- **`huggingface`** — get the base weights and host/push the result; `vllm` serves the merged-16bit at
+  throughput. This skill produces the artifact; those consume it.
+
+## Checklist
+
+- [ ] Fine-tuning is actually the right move and method is chosen (confirmed via `finetuning`).
+- [ ] Base model + license verified on its card (`open-weights`); using a current `unsloth/*-4bit` id.
+- [ ] `from_pretrained(load_in_4bit=True, max_seq_length=…)` → `get_peft_model(r, target_modules, …)`.
+- [ ] `get_chat_template` applied with the model's correct template.
+- [ ] `train_on_responses_only` applied AND the label mask decode-checked (answer-only).
+- [ ] Fits the one GPU (batch × grad-accum, `use_gradient_checkpointing="unsloth"`, `adamw_8bit`).
+- [ ] Exported for the target: merged_16bit (vLLM/re-host) or GGUF Q4_K_M/Q8_0 (Ollama/llama.cpp).
+- [ ] Any speed/VRAM/tier/model claim I stated is hedged + cited to docs.unsloth.ai (not memory).
+
+## References
+
+- [references/masking-and-templates.md](references/masking-and-templates.md) — `get_chat_template`
+  options, per-model `instruction_part`/`response_part` pairs, thinking-mode, the vision path, and the
+  label-mask sanity check.
+- [references/grpo.md](references/grpo.md) — GRPO end-to-end: `GRPOConfig`/`GRPOTrainer`, `vLLM`
+  `fast_inference`, a GSM8K reward-function set, and loss-type/DAPO knobs.
+- [references/export.md](references/export.md) — full export matrix (merged_16bit / lora / merged_4bit
+  / GGUF), quant-method table, `push_to_hub_*`, manual `convert_hf_to_gguf.py`, and the Ollama handoff.

package/skills/unsloth/evals/README.md

@@ -0,0 +1,10 @@
+# Evals for the `unsloth` skill
+
+`cases.yaml` is a routing + capability fixture, not an automated harness. For each `should_trigger`
+prompt, confirm the router picks `unsloth` (fast low-VRAM single-GPU fine-tuning + GGUF export). For
+each `should_not_trigger`, confirm it routes to the named sibling — method choice to `finetuning`,
+dataset to `training-data`, running the GGUF to `ollama`, throughput serving to `vllm`, base-model
+choice to `open-weights` — and not here. For the `capability` case, check the answer covers every
+`must_include` bullet: the from_pretrained→get_peft_model→SFTTrainer flow, response-only masking, GGUF
+export + the ollama handoff, the hedged speed/VRAM claim, and the single-GPU guardrail. No GPUs or
+network needed.

package/skills/unsloth/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: unsloth
+
+should_trigger:
+  - prompt: "I want to QLoRA fine-tune Llama-3.1-8B but it OOMs on my 16GB GPU — how do I make it fit?"
+    why: Core niche — fast, low-VRAM single-GPU fine-tuning; the fit problem is exactly what load_in_4bit + get_peft_model + adamw_8bit + unsloth gradient checkpointing solve.
+  - prompt: "How do I fine-tune gpt-oss on a single 24GB GPU roughly 2x faster with less VRAM?"
+    why: Names the backend's headline (2x/less-VRAM), a single GPU, and a supported MoE model — squarely this skill.
+  - prompt: "My chat fine-tune's loss looks like it's covering the user turn — how do I mask the prompt so it only trains on the response?"
+    why: The train_on_responses_only / get_chat_template masking problem, the load-bearing gotcha owned here.
+  - prompt: "After training my LoRA with Unsloth, how do I export it to GGUF Q4_K_M for Ollama?"
+    why: Export mechanics (save_pretrained_gguf, quant choice, handoff to ollama) are half of this skill.
+  - prompt: "Turn a base Qwen into a reasoning model with GRPO on one GPU using reward functions."
+    why: GRPO/reasoning FT via GRPOTrainer + fast_inference vLLM, the low-VRAM RL path this skill covers.
+  - prompt: "Vull ajustar un model a una sola GPU sense quedar-me sense VRAM amb Unsloth."
+    why: Catalan; single-GPU low-VRAM fine-tuning with Unsloth by name — the exact trigger.
+
+should_not_trigger:
+  - prompt: "Should I fine-tune, use RAG, or just prompt-engineer for my support bot? And SFT vs DPO?"
+    route_to: finetuning
+    why: The whether/why/which-method decision is the method layer, not the backend that makes it run.
+  - prompt: "How do I format my conversations into a JSONL messages dataset for fine-tuning?"
+    route_to: training-data
+    why: Dataset construction/quality; this skill assumes the dataset already exists.
+  - prompt: "I exported a GGUF — how do I run it locally, write a Modelfile, and size VRAM in Ollama?"
+    route_to: ollama
+    why: Running the exported artifact locally is Ollama's job; Unsloth stops at producing the file.
+  - prompt: "Serve my merged 16-bit model at high throughput with tensor parallelism and continuous batching."
+    route_to: vllm
+    why: Serving-engine flags/throughput are the serving skill, not the training backend.
+  - prompt: "Which open model and license should I pick as my base — Llama vs Qwen vs Gemma?"
+    route_to: open-weights
+    why: Base-model selection + license tradeoffs are the choosing layer, not the fine-tuning backend.
+
+capability:
+  - scenario: "I have one RTX 4090 (24GB). Fine-tune Llama-3.1-8B-Instruct on my chat JSONL with Unsloth so loss is only on the assistant turns, then export a Q4_K_M GGUF to run in Ollama. It keeps OOMing."
+    must_include:
+      - "FastLanguageModel.from_pretrained with load_in_4bit=True and max_seq_length, using a pre-quantized unsloth/*-bnb-4bit base id (verify the current id)."
+      - "get_peft_model with r/lora_alpha/target_modules and use_gradient_checkpointing='unsloth'; plus VRAM levers for OOM (batch size + gradient_accumulation_steps, optim='adamw_8bit')."
+      - "get_chat_template for the correct Llama-3.1 template AND train_on_responses_only with matching instruction_part/response_part so loss is response-only — with a decode/label sanity check."
+      - "Export via save_pretrained_gguf(quantization_method='q4_k_m') and the note that running it is an ollama job (create from the GGUF, run); merge to 16bit for vLLM instead."
+      - "The honesty hedge: the ~2x faster / ~70% less VRAM headline is model/GPU/config-specific vs a HF+FA2 QLoRA baseline — verify current numbers at docs.unsloth.ai and don't quote one number as gospel."
+      - "The single-GPU guardrail (OSS core is single-GPU; multi-GPU/multi-node is the paid/verify-live tier) and the boundary that method choice is finetuning, not this."

package/skills/unsloth/references/export.md

@@ -0,0 +1,75 @@
+# Export: from trained LoRA to a runnable artifact
+
+After `trainer.train()` you hold LoRA adapters on top of a (possibly 4-bit) base. Export depends on
+where it runs next. Tracks docs.unsloth.ai inference-and-deployment pages (accessed 2026-07).
+
+## The matrix
+
+| Target                     | Method                                                        | Notes |
+| -------------------------- | ------------------------------------------------------------- | ----- |
+| vLLM / re-host / portable  | `save_pretrained_merged(dir, tok, save_method="merged_16bit")`| Base + LoRA merged at 16-bit. The high-quality keeper. |
+| Small, hot-swappable       | `save_pretrained_merged(dir, tok, save_method="lora")`        | Adapters only (~MBs). Load onto the base at run time. |
+| Ollama / llama.cpp         | `save_pretrained_gguf(dir, tok, quantization_method="q4_k_m")`| Converts + quantizes to GGUF. |
+| DPO / niche 4-bit inference| `save_method="merged_4bit"`                                   | **Discouraged** — quality loss; only if a tool needs it. |
+
+## Merge to 16-bit (recommended keeper)
+
+```python
+model.save_pretrained_merged("model_16bit", tokenizer, save_method = "merged_16bit")
+# push instead of / in addition to saving:
+model.push_to_hub_merged("user/model", tokenizer,
+                         save_method = "merged_16bit", token = "hf_...")
+```
+
+`merged_16bit` is the format vLLM and most serving stacks expect. Prefer it over `merged_4bit` — merge
+at 16-bit, quantize downstream if you need to.
+
+## LoRA adapters only
+
+```python
+model.save_pretrained("finetuned_lora"); tokenizer.save_pretrained("finetuned_lora")
+# or save_pretrained_merged(..., save_method="lora")
+```
+
+Tiny and hot-swappable (e.g. vLLM LoRA hot-swap). Requires the base at inference time.
+
+## GGUF for Ollama / llama.cpp
+
+```python
+# one quant:
+model.save_pretrained_gguf("model_gguf", tokenizer, quantization_method = "q4_k_m")
+# several at once, pushed to the Hub:
+model.push_to_hub_gguf("user/model-gguf", tokenizer,
+                       quantization_method = ["q4_k_m", "q8_0", "f16"], token = "hf_...")
+```
+
+Quant guide (size vs quality — this is a real tradeoff, not free):
+
+| Method   | ~bits/weight | Use it for |
+| -------- | ------------ | ---------- |
+| `q4_k_m` | ~4.9         | Everyday default: ~half the size for a few % quality loss. |
+| `q5_k_m` | ~5.5         | A notch more quality than Q4 for a bit more size. |
+| `q8_0`   | ~8.5         | Near-lossless; larger. |
+| `f16`    | 16           | Unquantized ceiling; biggest. |
+
+Lower than Q4 (Q2/Q3) drops quality sharply — avoid unless desperate for size.
+
+### Manual conversion (when the helper can't, or you want control)
+
+Merge to 16-bit first, then run llama.cpp's converter:
+
+```bash
+python llama.cpp/convert_hf_to_gguf.py model_16bit \
+    --outfile model-F16.gguf --outtype f16 --split-max-size 50G
+# then quantize with llama.cpp's quantize tool to q4_k_m / q8_0, etc.
+```
+
+## Handoff — this skill stops at the file
+
+- **Run the GGUF locally →** `ollama`. Roughly: `ollama create <name> -f Modelfile` with
+  `FROM ./model-Q4_K_M.gguf`, then `ollama run <name>`. The Modelfile/quant/VRAM details are its job.
+  Unsloth's docs also show `OLLAMA_MODELS=unsloth ollama run merged_file.gguf` for a quick check.
+- **Serve merged-16bit at throughput →** `vllm` (engine flags, batching, LoRA hot-swap).
+- **Host/share the weights →** `huggingface` (the `push_to_hub_*` calls above land there).
+
+Export is the last thing this skill owns; running and serving belong to those siblings.