claude-ml-intern-skill

A Claude Code skill that turns the agent into an autonomous ML intern: it researches, implements, trains, self-verifies, and publishes ML code with the Hugging Face ecosystem. Telegram + Slack milestone alerts.

Behavioral port of huggingface/ml-intern as a single drop-in Claude Code skill — no extra daemon, no extra LLM client, no extra auth. The skill reuses the agent loop, tools, and auto-compaction that Claude Code already provides.

---

What it does

Given a single instruction like “implement DeepSeek-V3 at ~100M params and train on TinyStories”, the skill will, with no further input:

1. Restate the task and list unknowns → TASK.md
2. Clarify only if something is genuinely ambiguous — and only after trying to research the unknown first (a term/repo/paper you don’t recognize gets WebSearched and read before any question reaches you). Interactive runs ask via a bundled question; headless -p runs write best-guess defaults + fire approval_required and never hang.
3. Budget the run up front → BUDGET.md (max solution paths, max retries per path, compute cap in GPU-hours/wall-clock, scale + token ceilings). The budget bounds the parallel fan-out and the retry loop.
4. Research the architecture, dataset, and reference implementations using WebFetch + HF Hub API + GitHub code search → RESEARCH.md (URLs + section refs)
5. Plan files, hyperparameters, dataset slug, success criteria — plus the candidate solution paths the task admits (e.g. MLA vs MQA attention, HF building-block vs custom module) → PLAN.md
6. Implement each solution path in parallel via subagents — one background subagent per path, each owning the full implement → smoke-test → train → self-verify mini-pipeline in its own path-/ dir and returning a concise report. Runs concurrently by default (serializes on CUDA OOM). Single obvious path → single subagent. On agents without subagents (e.g. Codex CLI) the paths run inline and sequentially.
7. Smoke-test (per path): instantiate, print param count, run a forward pass on random tensors before any training
8. Train (per path) with NaN guard, LR schedule, checkpointing, eval, generation sampling at milestones
9. Self-verify (per path) → VERIFY.md with six independent verdicts (generation sanity, loss-vs-baseline, eval-tracks-train, data consumption, stderr scan, param-count drift). A low loss number alone never declares success — the skill exists in part because of a real failure where a model reported train_loss=0.03 / eval=0.02 but generated word salad (causal mask leak via the CSA Compressor).
10. Diagnose & redo failures — a failed path gets a path-/POSTMORTEM.md (symptom → root cause → fix) and a budgeted retry subagent with the fix applied; exhausted paths are dropped. The whole EXPERIMENTS.md ledger of paths/retries feeds the final comparison. error fires only if every path fails.
11. Aggregate → RESULTS.md picks the best passing path with a comparison table of all paths.
12. Publish to the Hub → fresh model repo at /ml-intern-- (from the winning path) with model.safetensors, config.json, model.py, and the full reproducibility bundle. URL written to PUBLISHED.md.
13. Notify Telegram + Slack at every milestone: plan_ready, code_ready, train_started, train_done, published, error, blocker, approval_required.

All run artifacts live under ~/ml-intern-runs// — shared files (TASK.md, BUDGET.md, PLAN.md, RESEARCH.md, EXPERIMENTS.md, RESULTS.md) at the root, per-path artifacts (train.log, VERIFY.md, ckpts/, POSTMORTEM.md) under path-/.

---

One-command install

Claude Code

curl -fsSL https://raw.githubusercontent.com/AlexWortega/claude-ml-intern-skill/main/install.sh | bash

This clones the skill into ~/.claude/skills/ml-intern/ and writes a starter .env. Open any claude session afterwards and type /ml-intern … (or just describe an ML task — the skill triggers on phrases like “implement”, “train”, “fine-tune”, “reproduce paper”).

On Windows (PowerShell), use the .ps1 installer:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/AlexWortega/claude-ml-intern-skill/main/install.ps1))) codex

Manual equivalent:

git clone https://github.com/AlexWortega/claude-ml-intern-skill ~/.claude/skills/ml-intern
cp ~/.claude/skills/ml-intern/.env.example ~/.claude/skills/ml-intern/.env

OpenAI Codex CLI (and any other agent that reads markdown instructions)

curl -fsSL https://raw.githubusercontent.com/AlexWortega/claude-ml-intern-skill/main/install.sh | TARGET=codex bash

This clones into ~/.codex/prompts/ml-intern/. Use the skill by reading SKILL.md at session start (e.g. codex --instructions ~/.codex/prompts/ml-intern/SKILL.md "implement Mamba-2 at 50M, train on enwik8").

For any other agent, the contract is just one file: SKILL.md is the system prompt; scripts/notify.sh and scripts/hf_push.sh are referenced from inside it.

---

Configuration

After install, fill in ~/.claude/skills/ml-intern/.env:

Missing tokens never crash a run — notify.sh is a graceful no-op when keys are absent. hf_push.sh does fail loudly without HF_TOKEN because a non-published run isn’t shipped.

---

Demonstration

End-to-end on a single RTX A6000 (46 GB), no human intervention beyond the initial prompt:

The V4 case is the most informative: skill received only the V4-Pro paper URL, autonomously read the upstream inference/model.py, identified the V4 deltas vs V3 (MQA + 512 head_dim, CSA / HCA, mHC hyper-connections, hash routing, sqrtsoftplus gate, swiglu_limit, O grouped low-rank, MTP, attention sink), implemented a 100M down-scale, ran a smoke test, caught a causal mask leak via the CSA Compressor during the first full-epoch run, diagnosed it itself, fixed it, regenerated samples, verified them, and re-ran.

Trained model

The TinyStories-trained DeepSeek-V4 100M from the run above:

→ https://huggingface.co/AlexWortega/ml-intern-v4-100m-tinystories-20260512-1721

Sample generation from the published checkpoint:

“Once upon a time, the little girl called Lucy went to the beach. She loved to play in the sand and splash in the sand. But one day, she got lost in the water. She called out for help, but nobody was around. Suddenly, Lucy saw a big wave coming towards her. She knew she needed to find a way to go back. She ran up to a nearby shore and carefully found her friends. She was so happy to have found her way back home.”

---

Layout

ml-intern/
  SKILL.md                              # frontmatter + behavior prompt
  install.sh                            # one-command installer (bash / macOS / Linux)
  install.ps1                           # one-command installer (PowerShell / Windows)
  scripts/
    notify.sh / notify.ps1              # TG + Slack POST, env-driven, no-op safe
    hf_search.sh / hf_search.ps1        # HF Hub search wrapper
    hf_push.sh / hf_push.ps1            # safetensors conversion + model card + push
  assets/
    deepseek_v3_100m_blueprint.md       # sizing reference for the V3 case
  .env.example

---

How the milestone events work

The skill calls bash scripts/notify.sh "" at every stage transition. Event names match upstream ML_INTERN_SLACK_AUTO_EVENTS so you can later move to the real ml-intern CLI without renaming anything:

• plan_ready — PLAN.md written
• code_ready — model.py + train.py compile + smoke-test passes
• train_started — training loop entered
• train_done — final loss + URL
• published — PUBLISHED.md written with the HF Hub URL
• error — fatal (NaN streak, broken VERIFY, upload failure)
• blocker — the agent is stuck and is asking for input

Both Telegram and Slack are POSTed in parallel; missing tokens for either channel silently skip that channel.

---

Why this exists

Manual reimplementations of new papers eat a day each before any signal arrives. The original huggingface/ml-intern solves this with its own agentic loop wired into LiteLLM + Anthropic / OpenAI / local backends. This skill ports the behavior of that loop into Claude Code so anyone already running claude can have the same intern available with no second LLM client and no second auth. The notification, doom-loop guard, context discipline, and milestone-event names are unchanged from upstream.

Beyond the port: this skill adds mandatory self-verification (VERIFY.md) and mandatory Hub publishing because a model in /tmp/ckpts/ only is not “shipped” and a low loss alone is not “trained”.

---

Credit

Behavior cloned from huggingface/ml-intern. All the smart design decisions (HF-first instinct, doom-loop guard, ML_INTERN_SLACK_AUTO_EVENTS event names, context discipline) are theirs. This repo is just the Claude Code skill packaging plus the verify-and-publish loop.

License: Apache 2.0.