thinking-machines-lab · zjrwtx · Mar 27, 2026
diff --git a/skills/tinker/SKILL.md b/skills/tinker/SKILL.md
@@ -0,0 +1,348 @@
+---
+name: tinker
+description: >
+  Use this skill whenever the user mentions Tinker, tinker CLI,
+  training runs, checkpoints, model fine-tuning with Tinker,
+  tinker-cookbook, tinker recipes, or any Thinking Machines AI
+  SDK operations. Also trigger when users ask about
+  listing/inspecting/downloading/deleting training checkpoints,
+  pushing checkpoints to HuggingFace, managing checkpoint TTL,
+  configuring post-training pipelines (SFT, RL, math RL,
+  code RL, distillation, preference learning, RLHF, tool use
+  training, multi-agent RL, prompt distillation, rubric
+  grading, VLM classification, Harbor RL), or working with
+  tinker:// paths. Use this skill even if the user just
+  mentions "tinker" in passing — it covers the full Tinker
+  ecosystem including CLI, Python SDK, and cookbook recipes.
+---
+
+# 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:
+```bash
+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
+
+```bash
+# Option 1: Environment variable (preferred)
+export TINKER_API_KEY="your-api-key"
+
+# Option 2: Config file (~/.tinker/config.json)
+mkdir -p ~/.tinker
+echo '{"api_key": "your-api-key"}' > ~/.tinker/config.json
+```
+
+### Verify Installation
+
+```bash
+tinker version
+tinker run list --limit 3
+```
+
+### Tinker Path Format
+
+All checkpoint operations use **tinker paths**:
+
+```
+tinker://<RUN_ID>/<TYPE>/<STEP>
+```
+
+- `TYPE`: `weights` (training) or `sampler_weights` (sampler)
+- Example: `tinker://run-abc123/weights/00040`
+
+---
+
+## CLI Commands
+
+### Global Options
+
+- `--format [table|json]` or `-f` — output format
+  (default: table)
+- `-h` / `--help` — help on any command
+
+### Run Commands
+
+```bash
+# List training runs (default: 20, use --limit=0 for all)
+tinker run list [--limit N] [-c COLUMNS]
+
+# Available columns:
+#   id, model, owner, lora, updated, status,
+#   checkpoint, checkpoint_time
+# Default columns: id, model, lora, updated, status
+
+# Show detailed info for a specific run
+tinker run info <RUN_ID>
+```
+
+### Checkpoint Commands
+
+```bash
+# List checkpoints (all runs, or filter by --run-id)
+tinker checkpoint list [--run-id ID] [--limit N]
+
+# Show checkpoint details
+tinker checkpoint info <TINKER_PATH>
+
+# Download and extract checkpoint locally
+tinker checkpoint download <TINKER_PATH> \
+  [-o OUTPUT_DIR] [--force]
+
+# Toggle public access
+tinker checkpoint publish <TINKER_PATH>
+tinker checkpoint unpublish <TINKER_PATH>
+
+# Set or remove expiration (TTL in seconds)
+tinker checkpoint set-ttl <TINKER_PATH> --ttl 604800
+tinker checkpoint set-ttl <TINKER_PATH> --remove
+
+# Delete checkpoints (by path or by filters)
+tinker checkpoint delete <PATH1> [PATH2 ...] [-y]
+tinker checkpoint delete --run-id <ID> \
+  [--type weights|sampler_weights] \
+  [--before DATE] [--after DATE] [-y]
+
+# Push checkpoint to HuggingFace Hub
+tinker checkpoint push-hf <TINKER_PATH> \
+  [-r REPO_ID] [--public] [--revision REV] \
+  [--commit-message MSG] [--create-pr] \
+  [--allow-pattern PAT] [--ignore-pattern PAT] \
+  [--no-model-card]
+```
+
+> For full flag details and output format examples,
+> read `references/cli-reference.md`.
+
+---
+
+## Common Workflows
+
+### 1. Find and Download a Checkpoint
+
+```bash
+# Step 1: Find your training run
+tinker run list
+
+# Step 2: Inspect the run
+tinker run info <RUN_ID>
+
+# Step 3: List available checkpoints
+tinker checkpoint list --run-id <RUN_ID>
+
+# Step 4: Download
+tinker checkpoint download \
+  tinker://<RUN_ID>/weights/<STEP> \
+  -o ./models/ --force
+```
+
+### 2. Push a Checkpoint to HuggingFace
+
+```bash
+# Prerequisite: authenticate with HF
+# pip install huggingface_hub && hf auth login
+
+# Push as public PEFT adapter
+tinker checkpoint push-hf \
+  tinker://<RUN_ID>/sampler_weights/<STEP> \
+  -r myorg/my-lora --public
+
+# Or create a PR instead of direct push
+tinker checkpoint push-hf \
+  tinker://<RUN_ID>/sampler_weights/<STEP> \
+  -r myorg/my-lora --create-pr
+```
+
+### 3. Clean Up Old Checkpoints
+
+```bash
+# Delete checkpoints older than a date
+tinker checkpoint delete --run-id <RUN_ID> \
+  --type weights --before 2025-01-01 -y
+
+# Delete specific checkpoints
+tinker checkpoint delete \
+  tinker://<RUN_ID>/weights/0001 \
+  tinker://<RUN_ID>/weights/0002 -y
+```
+
+### 4. Scripting with JSON Output
+
+```bash
+# Export all runs as JSON
+tinker --format json run list --limit=0 > runs.json
+
+# Parse with jq
+jq '.runs[].training_run_id' runs.json
+
+# Batch list checkpoints per run
+for rid in $(jq -r '.runs[].training_run_id' runs.json)
+do
+  tinker --format json checkpoint list --run-id "$rid"
+done
+```
+
+---
+
+## 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:
+
+```python
+import chz
+from tinker_cookbook.rl import train  # or supervised
+
+# 1. Build a typed config via chz.Blueprint
+def build_config_blueprint() -> chz.Blueprint[train.Config]:
+    return chz.Blueprint(train.Config).apply({
+        "model_name": "meta-llama/Llama-3.1-8B",
+        "learning_rate": 2e-4,
+        ...
+    })
+
+# 2. Run the training loop
+def main(config):
+    asyncio.run(train.main(config))
+
+# 3. CLI entry point with chz overrides
+if __name__ == "__main__":
+    bp = build_config_blueprint()
+    bp.make_from_argv(sys.argv[1:])
+    main(bp.make())
+```
+
+Override any config field from the command line:
+```bash
+python -m tinker_cookbook.recipes.sl_basic \
+  --model_name "Qwen/Qwen3-8B" \
+  --learning_rate 1e-4 \
+  --log_path /tmp/my-run
+```
+
+### Running SFT (Supervised Fine-Tuning)
+
+```bash
+# Minimal SFT on NoRobots dataset
+python -m tinker_cookbook.recipes.sl_basic
+
+# With custom dataset (JSONL of conversations)
+# Edit sl_basic.py to use FromConversationFileBuilder:
+#   file_path="/path/to/conversations.jsonl"
+# Format: same as example_data/conversations.jsonl
+```
+
+### Running RL Training
+
+```bash
+# Math RL on GSM8K
+python -m tinker_cookbook.recipes.rl_basic
+
+# Override hyperparameters
+python -m tinker_cookbook.recipes.rl_basic \
+  --learning_rate 4e-5 \
+  --max_tokens 256
+```
+
+### Available Recipes
+
+| Recipe | Type | Use Case |
+|--------|------|----------|
+| `sl_basic` | SFT | Minimal SFT template |
+| `rl_basic` | 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
+
+```python
+from tinker_cookbook import model_info
+
+# Get the right renderer for a model
+renderer = model_info.get_recommended_renderer_name(
+    "meta-llama/Llama-3.1-8B"
+)
+
+# Checkpoint save/resume
+from tinker_cookbook import checkpoint_utils
+resume = checkpoint_utils.get_last_checkpoint(log_path)
+```
+
+### 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 `~/.tinker/config.json` |
+| 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