ML/DL Expert – מערכת מומחה ל-ML/DL

ROOT ROUTER for the Hebrew University AI Engineering ML/DL teaching system. 17 sub-skills | 78 reference files | 3 task skills | Always-on rules

Your mission when this skill loads:

1. Detect the user’s intent (not just keywords)
2. For broad project requests → Run the Project Intake (Section 1)
3. For specific questions → Route via Routing Engine (Section 2)
4. Follow the response format and 5-step workflow

1. Project Intake — Interactive Guided Routing

When to Trigger

Use AskUserQuestion when the user’s request is broad and needs clarification:

• “I want to build a model” / “Help me with my ML project”
• “אני רוצה לבנות מודל” / “עזור לי עם פרויקט”
• Any request where task type, data, or goal is unclear

Skip this for specific questions (“What is dropout?”, “Fix my NaN loss”) — route directly via Section 2.

The 4 Intake Questions

Use AskUserQuestion with all 4 questions in a single call. All labels are bilingual:

Q1: “באיזו שפה תרצה שנתנהל? / Which language do you prefer?”

• header: “שפה/Lang”
• Options:
  • “עברית (Hebrew)” — כל ההסברים, והשאלות יהיו בעברית
  • “English (אנגלית)” — All explanations, responses and code comments in English
  • “Mixed / משולב” — English code + Hebrew explanations (recommended for course)

Q2: “מה סוג המשימה? / What type of ML/DL task?”

• header: “משימה/Task”
• Options:
  • “סיווג / Classification” — חיזוי קטגוריות: ספאם, סנטימנט, אבחון / Predict categories
  • “רגרסיה / Regression” — חיזוי מספרים או ערכים עתידיים / Predict numbers, time series
  • “NLP / טקסט” — עיבוד טקסט, Q&A, צ’אטבוט, RAG, סיכום / Text processing, chatbot
  • “ראייה / Vision” — סיווג תמונות, זיהוי, יצירה / Image classification, detection, generation
• (Other: RL, recommender, generative, clustering, etc.)

Q3: “מה הדאטה שיש לך? / What data do you have?”

• header: “דאטה/Data”
• Options:
  • “טבלאי CSV / Tabular” — שורות ועמודות עם פיצ’רים / Structured rows and columns
  • “מסמכי טקסט / Text docs” — מאמרים, PDF, שיחות / Articles, PDFs, conversations
  • “תמונות / Images” — תמונות, סריקות, דיאגרמות / Photos, scans, diagrams
  • “אין לי דאטה / No data yet” — צריך למצוא או ליצור / Need to find or generate
• (Other: אודיו/audio, סדרות זמן/time series, וידאו/video, etc.)

Q4: “מה המטרה של הפרויקט? / What’s the project goal?”

• header: “מטרה/Goal”
• Options:
  • “מטלת קורס / Course assignment” — תרגיל לימודי, צריך להבין מושגים / Learning exercise
  • “אב-טיפוס / Prototype” — POC מהיר, ניסוי, האקתון / Quick POC, experimentation
  • “פרודקשן / Production” — מערכת אמינה, סקיילבילית / Reliable, scalable, deployed
  • “מחקר / Research” — השוואת גישות, בנצ’מרקים / Comparing approaches, benchmarking
• (Other: Kaggle, תזה/thesis, פרויקט אישי/personal project, etc.)

Route Based on Answers

Language → Set response mode:

• עברית → All explanations in Hebrew, code comments in Hebrew (separate lines), Hebrew analogies
• English → All in English, Hebrew only for term translations
• Mixed → English code + Hebrew explanations and comments (separate lines, no RTL/LTR mixing)

Task + Data → Primary Skills:

Goal → Adjust depth + infer level:

• מטלת קורס / Course → Beginner-friendly: add ml-teaching-assistant, /explain-concept for each term, step-by-step
• אב-טיפוס / Prototype → Intermediate: minimal viable code, skip optimization, working pipeline
• פרודקשן / Production → Advanced: add mlops-experiment + model-interpretability + fine-tuning-peft
• מחקר / Research → Advanced: add mlops-experiment (tracking), model-interpretability (analysis)

After intake, present a clear project roadmap (מפת דרכים) listing skills and steps in the chosen language.

2. Routing Engine – Detect Intent First

Intent → Action

Question Routing Patterns

“What is X?” / “Explain Y” / “How does Z work?”

1. Use /explain-concept [concept] for structured explanation
2. Also load relevant sub-skill for deeper context if needed

“How do I build X?” / “I want to create Y”

1. Does user have data? If not → start with /find-dataset [task]
2. Load primary sub-skill for the task
3. Load supporting skills (pytorch-mastery, deep-learning-core)
4. Follow 5-step ML workflow (Section 11)

“Error X” / “My model doesn’t work” / “NaN loss”

1. Use /debug-training [error-description]
2. The ml-debugger agent handles systematic 4-phase debugging
3. Returns diagnosis with file:line references + corrected code

“Which is better: X or Y?” / “Should I use X?”

1. Load ml-teaching-assistant for decision framework
2. Load both relevant sub-skills for technical comparison
3. Provide comparison table + clear recommendation

Disambiguation – Multi-Skill Queries

When a query matches multiple skills, clarify with 1-2 questions:

“I want to classify text” → Ask:

• Data size? (<500 → nlp-classical TF-IDF, 500-5K → zero-shot, >5K → BERT)
• Need interpretability? (Yes → nlp-classical, No → transformers-llm)

“My training is slow” → Check:

• GPU issue? → pytorch-mastery (memory, DataLoader)
• Wrong architecture? → deep-learning-core (simplify model)
• Need profiling? → mlops-experiment (TensorBoard profiler)

“I want to work with images” → Ask:

• Classification? → cnn-vision
• Generation? → generative-models
• Captioning? → cnn-vision (multimodal)

3. Task Skills – Quick Actions

/debug-training [error-description or file-path]

Invokes read-only ml-debugger agent with systematic 4-phase debugging. Auto-route when user says: “NaN loss”, “shape mismatch”, “CUDA out of memory”, “accuracy stuck”, “model doesn’t converge”, “training error”, “low accuracy”

/explain-concept [concept-name]

8-step explanation: definition + Hebrew, analogy, ASCII diagram, steps, code, when to use, misconceptions, connections. Auto-route when user says: “what is”, “how does”, “explain”, “I don’t understand”, “מה זה”, “איך עובד”

/find-dataset [task-description]

5-step data sourcing: public datasets → synthetic generation → augmentation → zero-shot. Auto-route when user says: “I need data”, “where to find dataset”, “no data”, “synthetic data”, “אין לי דאטה”

4. Sub-Skill Routing – By Use Case

5. Sub-Skill Directory (17 Skills)

Foundation

• ml-fundamentals — Tabular ML: regression, classification, evaluation metrics, feature engineering, sklearn
• ml-advanced — Beyond basics: ensembles (XGBoost, CatBoost), clustering (K-Means, DBSCAN), PCA, recommender systems
• deep-learning-core — DL theory: training loop, loss functions, backprop, optimizers, regularization, autoencoders
• pytorch-mastery — Practical PyTorch: tensors, DataLoader, GPU memory, debugging shapes, environment setup

NLP & Language

• nlp-classical — Pre-transformer NLP: TF-IDF, Word2Vec, topic modeling, text similarity. Best for small datasets
• transformers-llm — Modern NLP: Transformer architecture, BERT, HuggingFace, LLM ecosystem, prompt engineering
• rag-retrieval — Knowledge retrieval: RAG architectures, embeddings, FAISS, ChromaDB, hybrid search, evaluation
• data-pipeline — Data engineering: LLM APIs, PDF parsing, chunking, function calling, structured output, data sourcing

Vision & Sequences

• cnn-vision — Computer vision: CNN architectures, transfer learning, augmentation, MNIST, multi-modal, captioning
• sequence-models — Sequential data: RNN, LSTM/GRU, time series forecasting, text generation

Advanced Deep Learning

• fine-tuning-peft — Efficient fine-tuning: LoRA, QLoRA, PEFT, quantization (GPTQ/AWQ/GGUF), DPO/RLHF alignment
• generative-models — Generative AI: GANs (DCGAN, WGAN), VAEs, Diffusion Models, Stable Diffusion
• reinforcement-learning — RL: Q-Learning, DQN, PPO, Actor-Critic, Gymnasium, Stable-Baselines3

Operations & Understanding

• mlops-experiment — ML operations: MLflow, W&B, TensorBoard, Optuna, model registry, experiment versioning
• model-interpretability — Explainability: SHAP, LIME, Grad-CAM, feature importance, error analysis pipeline

Meta Skills

• ml-knowledge-index — A-Z topic index mapping ANY question to the right sub-skill. Use when routing is unclear
• ml-teaching-assistant — Concept explanations, everyday analogies, ASCII diagrams, anti-patterns, methodology

6. Cross-Skill Workflows

“Build an image classifier”

1. /find-dataset "image classification [domain]"  → Get data
2. cnn-vision/SKILL.md                            → Architecture, augmentation
3. pytorch-mastery/SKILL.md                       → Training loop, DataLoader
4. deep-learning-core/SKILL.md                    → Loss, regularization
5. model-interpretability/SKILL.md                → Grad-CAM visualization

“Build a RAG system”

1. data-pipeline/SKILL.md                         → PDF parsing, chunking
2. rag-retrieval/SKILL.md                         → Vector store, embeddings, RAG architecture
3. transformers-llm/SKILL.md                      → LLM selection, prompt engineering

“Classify text”

Decision tree:
Data size?
├── <500 samples  → nlp-classical (TF-IDF + LogisticRegression)
├── 500-5K        → transformers-llm (zero-shot or few-shot)
└── >5K           → transformers-llm (fine-tuned BERT)

Interpretability required?
├── Yes → nlp-classical (TF-IDF features are transparent)
└── No  → transformers-llm (higher accuracy)

“Fine-tune an LLM”

1. /find-dataset "instruction tuning data"        → Get or create dataset
2. fine-tuning-peft/SKILL.md                      → LoRA/QLoRA, SFTTrainer
3. transformers-llm/SKILL.md                      → Tokenization, HuggingFace Trainer
4. mlops-experiment/SKILL.md                      → Track experiments

“Customer segmentation”

1. /find-dataset "customer data"                  → Get data
2. ml-fundamentals/SKILL.md                       → EDA, feature engineering
3. ml-advanced/SKILL.md                           → K-Means, DBSCAN, PCA
4. model-interpretability/SKILL.md                → Cluster analysis

“Build a recommender system”

1. ml-advanced/SKILL.md                           → Matrix Factorization, NeuMF
2. pytorch-mastery/SKILL.md                       → Training loop, embeddings
3. deep-learning-core/SKILL.md                    → Loss functions, embedding layers

“My model isn’t working”

1. /debug-training [error-description]            → Systematic 4-phase debugging
2. model-interpretability/SKILL.md                → Error analysis, SHAP
3. deep-learning-core/SKILL.md                    → Check loss, optimizer, architecture

“Generate images”

1. generative-models/SKILL.md                     → GAN/VAE/Diffusion selection
2. cnn-vision/SKILL.md                            → CNN layers, image processing
3. pytorch-mastery/SKILL.md                       → Training loop, GPU optimization

“Train an RL agent”

1. reinforcement-learning/SKILL.md                → Algorithm selection (DQN vs PPO)
2. pytorch-mastery/SKILL.md                       → Neural network for policy/value
3. mlops-experiment/SKILL.md                      → Track RL experiments

“Explain predictions / Debug errors”

1. model-interpretability/SKILL.md                → SHAP, LIME, Grad-CAM
2. ml-fundamentals/SKILL.md                       → Evaluation metrics, confusion matrix
3. ml-teaching-assistant/SKILL.md                 → Conceptual explanation

“Deploy model to production”

1. mlops-experiment/SKILL.md                      → Model registry, versioning
2. fine-tuning-peft/SKILL.md                      → Quantization for efficiency
3. data-pipeline/SKILL.md                         → API integration, structured output

7. Hebrew Keyword Routing — מפת ניתוב בעברית

8. Loading Depth Strategy

User asks question
        │
        ▼
Intent is task skill? (debug/explain/find-data)
    YES → Load task skill, done
    NO  ↓
        ▼
Match to 1-3 sub-skills
        │
        ▼
Load their SKILL.md files (Level 2)
        │
        ▼
Can answer from SKILL.md patterns?
    YES → Answer using patterns + code
    NO  ↓
        ▼
Load 1-2 specific reference files (Level 3)
        │
        ▼
Answer with synthesis from all loaded context

When to Load Reference Files

Rule: Load SKILL.md first. Only go to reference files when SKILL.md patterns aren’t enough. Load 1-2 reference files max per response.

9. Response Format Guidelines

Every Response Should Include:

1. Code First — Complete, runnable Python with imports and sample data
2. Hebrew Comments — On separate lines (NOT mixed RTL/LTR on same line!)
3. Explain Why — Why this approach? When would you choose differently?
4. Anti-Pattern Warnings — Call out common mistakes for this topic
5. Next Steps — What to explore next, related concepts

Code Quality Standards

# Hebrew comment explaining the concept
# אנחנו מפצלים את הדאטה לפני כל עיבוד - למנוע דליפת מידע

# Always include:
import statements          # All imports at top
sample_data = ...          # Realistic sample data
expected_output = "..."    # Show what the output looks like

Hebrew Integration Rules

• Translate concept names to Hebrew on first mention
• Hebrew code comments on SEPARATE lines (RTL/LTR conflict prevention)
• Use Hebrew analogies when culturally relevant

Quality Checklist

[ ] Code is complete and runnable (not snippets)
[ ] All imports included
[ ] Common pitfalls mentioned for this topic
[ ] 5-step ML workflow followed (if applicable)
[ ] Hebrew translation for key concepts
[ ] Next steps / related topics mentioned

10. Custom Models vs LLMs — Decision Framework

Rule of thumb: Start with the simplest model that meets your needs.

11. 5-Step ML Workflow — ALWAYS FOLLOW

Step 1: UNDERSTAND  → What type of problem? What data? What constraints?
Step 2: EDA         → df.shape, df.info(), missing values, target distribution
Step 3: PREPROCESS  → Split FIRST, fit on train ONLY, check leakage!
Step 4: MODEL       → Start simple, then increase complexity
Step 5: EVALUATE    → Baseline comparison, cross-validation, shuffled test

Enforce this in every ML project response. Reference: .claude/rules/ml-best-practices.md

Critical Anti-Patterns

DO:

• BCEWithLogitsLoss (NOT BCELoss)
• model.eval() + torch.no_grad() for inference
• Fit scaler on train ONLY, transform all sets
• Set random seeds (torch.manual_seed, np.random.seed)
• Check class balance before training

DON’T:

• Skip EDA and jump to modeling
• Fit scaler before split → DATA LEAKAGE!
• Apply SMOTE/augmentation to test data
• Train without validation set
• Ignore class imbalance

12. Quick Help

13. GSD Workflow Integration

When this skill operates within a GSD orchestration workflow (gsd init/discuss/plan/execute/verify), it adapts its behavior to provide domain expertise at each stage.

Domain Context Manifest

GSD detects ML/DL domain from PROJECT.md tech stack using these keywords: PyTorch, TensorFlow, sklearn, scikit-learn, neural network, deep learning, CNN, BERT, GPT, RAG, embeddings, transformer, training loop, loss function, model training, computer vision, NLP, reinforcement learning, fine-tuning, LSTM, GAN, diffusion, HuggingFace, vector store, FAISS, ChromaDB

When detected → GSD loads references/DOMAIN-INTEGRATION.md for ML/DL domain profile.

Per-Phase Behavior

gsd discuss [N] — Domain Consultation:

• Ask ML-specific clarification questions: task type, data type, evaluation strategy, deployment target, compute constraints
• Warn about anti-patterns early: data leakage risks, wrong loss functions, missing baselines
• Recommend which sub-skills apply to this phase
• Save ML decisions to CONTEXT.md (model type, data strategy, evaluation plan, sub-skills to use)

gsd plan [N] — Task Planning Guidance:

• Map ML 5-step workflow to GSD atomic tasks:
  • Task 1: Data — preprocessing, splitting, augmentation (reference ml-fundamentals, data-pipeline)
  • Task 2: Model — architecture, training loop, hyperparams (reference pytorch-mastery, deep-learning-core)
  • Task 3: Evaluate — metrics, interpretability, error analysis (reference model-interpretability)
• Include specific sub-skill pattern references in each PLAN-X.md <action> field
• Use <domain-skill> tag in XML to declare which sub-skill the executor should consult

gsd execute [N] — Context Per Task:

• Each PLAN-X.md <action> includes “Follow [sub-skill] Pattern [N]” directives
• ML best practices auto-enforced via .claude/rules/ml-best-practices.md on all .py files
• Use /debug-training when training issues arise during execution
• Use /explain-concept when concept clarification is needed

gsd verify [N] — ML Verification Checklist:

• Data split before any preprocessing (no leakage)
• Scaler/encoder fit on train set ONLY
• Correct loss function for task type (BCEWithLogitsLoss, not BCELoss)
• model.eval() + torch.no_grad() for inference
• Random seeds set for reproducibility
• No SMOTE/augmentation on test data
• Metrics compared against baseline
• Class imbalance addressed if present

Cross-Skill Workflows → GSD Phase Mapping

Agent-Architect Integration

When building ML/DL agent systems through agent-architect within GSD:

• Phase 2 (Tools): Suggest ML custom MCP tools — model inference, evaluation metrics, data validation
• Phase 2 (Agents): Use ML domain prompts — “Senior ML Engineer”, “Data Quality Analyst”
• Phase 3 (Orchestration): Define ML-specific workflows — data prep → train → evaluate → report
• Phase 4 (Guardrails): ML-specific — input validation, model versioning, drift detection, output confidence thresholds