organize-ml-workspace
Decide where files live in an ML experimentation project: reusable code in `src/<pkg>/`, one `# %%` script per experiment in `experiments/`, design notes + index in `journal/`, reports in `reports/`, agent-only probes in `scratch/`. Owns the layout, the file-creation rules (one file per experiment, ask before editing), and the jupytext `# %%` script convention. Never imposes `data/` — the user owns that. TRIGGER — any of: - Starting a new ML project / scaffolding a workspace. - About to create the first experiment file in a project. - About to create `src/<pkg>/data.py` / `features.py` / `pipeline.py` / `evaluate.py` for the first time. - About to write a `.ipynb` for experimentation — redirect to a `# %%` script under `experiments/`. - User asks where something should live, how to organize the project, or how to set up the workspace. - About to add a new experiment iteration — decide new file vs edit existing (ask the user). SKIP when: the file is clearly part of an already-populated
probabl-ai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add probabl-ai/skills --skill organize-ml-workspace技能说明
name: organize-ml-workspace
description: >
Decide where files live in an ML experimentation project: reusable
code in src/<pkg>/, one # %% script per experiment in
experiments/, design notes + index in journal/, reports in
reports/, agent-only probes in scratch/. Owns the layout, the
file-creation rules
(one file per experiment, ask before editing), and the jupytext
# %% script convention. Never imposes data/ — the user owns
that.
TRIGGER — any of:
- Starting a new ML project / scaffolding a workspace.
- About to create the first experiment file in a project.
- About to create
src/<pkg>/data.py/features.py/pipeline.py/evaluate.pyfor the first time. - About to write a
.ipynbfor experimentation — redirect to a# %%script underexperiments/. - User asks where something should live, how to organize the project, or how to set up the workspace.
- About to add a new experiment iteration — decide new file vs edit existing (ask the user).
SKIP when: the file is clearly part of an already-populated
module (e.g., adding a function to existing features.py); pure
refactor inside a single existing file; pipeline declaration
mechanics (build-ml-pipeline); evaluation mechanics
(evaluate-ml-pipeline); skore symbol lookup (python-api).
HOW TO USE: first run the Detection table below — if any
signal matches, glue to existing conventions (do not rename or
move folders). If no signal matches, scaffold the default
layout. Emit the Pre-flight checklist as visible text and read
the Stop conditions before any file is created or edited. Use
templates in templates/; copy and adapt, do not rewrite from
scratch.
Organize ML Workspace
Where things live, when to create a new file, what each file is allowed to contain.
Next-step pointers — where you go after this skill
| You came here for… | → next |
|---|---|
| Bootstrap a fresh workspace | → python-env-manager § Bootstrap; then iterate-ml-experiment § 0 |
| First experiment script | → iterate-ml-experiment § 0 for the design note |
| Add a new experiment iteration | → iterate-ml-experiment § 1 (new vs edit decision) |
| Pipeline / evaluate / smoke-test content | → build-ml-pipeline / evaluate-ml-pipeline / smoke-test-ml-pipeline |
Always re-emit the Pre-flight checklist with evidence before declaring the turn done.
Sibling skills — open just-in-time
Don't pre-read every sibling at session start (paralysis). Open each
sibling SKILL.md when a step calls for it (e.g. open
python-env-manager before G-ENV-MGR; open iterate-ml-experiment
before handing off the design-note write). Emit this tracker once
per turn:
Sibling skills (just-in-time):
- data-science-python-stack, python-env-manager, python-api,
python-code-style, iterate-ml-experiment, explore-ml-data,
build-ml-pipeline, evaluate-ml-pipeline, test-ml-pipeline,
smoke-test-ml-pipeline
Stop conditions — read before anything else
- Missing dependency. If
import skoreraises, STOP. Invokepython-env-managerfor the install command. Do not dropskore.Projectin favor ofmlflow/ pickles / "print metrics" — the workspace contract assumes a Project on disk. - Symbol from memory is forbidden. Any
skore.Project/project.put/skore.evaluatesignature must come from apython-apicall this turn. - Existing layout wins — detect first. Run the Detection table before scaffolding. Don't rename, relocate, or "tidy up" existing folders.
- Notebooks are not silent. Existing
.ipynbfiles in the experiment folder → surface the convention shift and ask. Don't auto-convert. - Scratch is read-only against the skore Project. Probes under
scratch/<ts>_<short>.pymay callproject.get(...),project.summarize(), walk an existing report. They MUST NOT callskore.evaluate(...)orproject.put(...). Whenproject.get(key)raisesKeyError, the fix is the lookup shape:getis by id, not bykey. Usesummarize()→(key, id)→get(id). Never substitute by re-runningevaluate+put. - Tabular library is asked, not assumed (G-TABULAR). Pandas
being importable via skore is not a pick. Invoke
data-science-python-stackfor the structured ask. Free-text ("quick", "you pick") does NOT resolve. Persisted in JOURNAL.md StatusWorkspace decisions. - Package name is asked, not inferred (G-PKG-NAME). Before any
pyproject.toml/ manifest creation (includingpixi init/uv init/poetry init), fire anAskUserQuestionfor thesrc/<pkg>/import name. Folder name in snake_case is the default. Manifest creation before G-PKG-NAME passes is forbidden — runninginitfirst creates a[project] nameentry, and reading "name is in the manifest" back is circular. If a manifest exists, confirm viaAskUserQuestion— continuity from a prior session is not continuity from a user decision. - Skore Project mode is asked, not assumed (G-SKORE-MODE).
Before any template instantiation containing
skore.Project(...), fire anAskUserQuestionforlocal|hub|mlflow. Default proposal:local. All three are always offered; a detected hub config in the CWD (config.toml/SKH__*/ cached login) only influences the default, never prunes the choices. Hub triggers a follow-up for the workspace name (org/team on the hub — distinct from local-modeworkspace=); mlflow triggers a follow-up for the MLflow tracking server URI (tracking_uri=) — the agent cannot infer it. Persists asskore mode:(+skore hub workspace:when hub, +skore mlflow tracking uri:when mlflow). Without it the<SKORE_PROJECT_INIT>substitution has no shape to fill. Details: →references/g_skore_mode.md. - Switching skore mode mid-project is forbidden by default. Once recorded, do not silently change. A swi