Tinker SDK Skill

Tinker is an ML platform SDK by Thinking Machines AI for
managing training runs, model checkpoints, and fine-tuning
workflows. This skill covers the CLI, Python SDK, and the
tinker-cookbook training recipes.

Source repos:

• - SDK: https://github.com/thinking-machines-lab/tinker
• Cookbook: https://github.com/thinking-machines-lab/tinker-cookbook
• This skill: https://github.com/zjrwtx/max_skills

IMPORTANT — Always use the latest version:
Before running any Tinker command or cookbook recipe,
ensure the latest version is installed:

uv pip install --upgrade tinker
# For cookbook, pull latest and reinstall:
cd <cookbook-dir> && git pull && uv pip install -e .

When you need more detailed information about API
internals, recipe implementations, or SDK source code,
always check the latest code from these repos — do NOT
rely on cached or outdated knowledge. Clone or browse
the repos directly to get up-to-date APIs and options.

Quick Start

Authentication

CODEBLOCK1

Verify Installation

CODEBLOCK2

Tinker Path Format

All checkpoint operations use tinker paths:

CODEBLOCK3

• - TYPE: weights (training) or sampler_weights (sampler)
• Example: INLINECODE3

---

CLI Commands

Global Options

• - --format [table|json] or -f — output format

(default: table)

• - -h / --help — help on any command

Run Commands

CODEBLOCK4

Checkpoint Commands

CODEBLOCK5

For full flag details and output format examples,
read references/cli-reference.md.

---

Common Workflows

1. Find and Download a Checkpoint

CODEBLOCK6

2. Push a Checkpoint to HuggingFace

CODEBLOCK7

3. Clean Up Old Checkpoints

CODEBLOCK8

4. Scripting with JSON Output

CODEBLOCK9

---

Cookbook Recipes

The tinker-cookbook provides ready-to-use training recipes.
Repo: https://github.com/thinking-machines-lab/tinker-cookbook

Recipe Architecture

Every recipe follows the same pattern:

CODEBLOCK10

Override any config field from the command line:
CODEBLOCK11

Running SFT (Supervised Fine-Tuning)

CODEBLOCK12

Running RL Training

CODEBLOCK13

Available Recipes

Recipe	Type	Use Case
INLINECODE9	SFT	Minimal SFT template
INLINECODE10

RL | Minimal RL template | | chat_sl/ | SFT | Conversations (Tulu3) | | math_rl/ | RL | Math reasoning (GSM8K) | | code_rl/ | RL | Code (sandboxed exec) | | preference/ | RLHF | SFT → reward → RL | | search_tool/ | RL | Retrieval tool use | | distillation/ | SFT/RL | Teacher→student | | prompt_distillation/ | SFT | Internalize prompts | | multiplayer_rl/ | RL | Self-play / multi-agent | | rubric/ | RL | LLM grader rubrics | | verifiers_rl/ | RL | Community envs | | vlm_classifier/ | SFT | Vision-language | | harbor_rl/ | RL | Terminal/SWE tasks |

Key Utilities

CODEBLOCK14

Supported Models

Llama 3.x, Qwen 3/3.5, DeepSeek V3, Nemotron 3,
Kimi K2/K2.5, GPT-OSS, and 30+ more. Each model has
a recommended renderer in model_info.py.

For recipe deep-dives, renderer details, dataset
builder patterns, and RL environment setup, read
references/cookbook-recipes.md.

---

Quick Troubleshooting

Problem	Fix
Auth failure	Check TINKER_API_KEY or INLINECODE26
Checkpoint not found

Verify path format tinker://RUN/TYPE/STEP; list available with tinker checkpoint list --run-id ID | | Download fails | Use --force to overwrite; check disk space | | Cookbook import error | uv pip install -e . in cookbook dir; needs Python 3.10+ | | chz override syntax | --field value (flat) or --outer.inner value (nested) | | Rate limit | Wait and retry; reduce --limit for batch ops | | HF push fails | Run hf auth login; install huggingface_hub |

For the full error catalog, read
references/troubleshooting.md.

---

Detailed References

When the SKILL.md cheat sheet is not enough:

• - references/cli-reference.md — Every flag, output

format example (table + JSON), exit codes, date format rules, bulk delete filter logic

• - references/cookbook-recipes.md — Per-recipe config

fields, renderer selection, dataset builder interface, RL environment pattern, hyperparameter guidance

• - references/troubleshooting.md — Extended error

catalog with 15+ error-to-fix mappings, network/proxy issues, W&B integration, checkpoint corruption