/tsk-config

name: tsk-config
description: Use this skill when the user wants to set up or configure tsk Docker container images, customize their tsk.toml for Docker builds, configure stack/agent/project layers, or troubleshoot tsk container build issues.
user-invocable: true
disable-model-invocation: true
allowed-tools: Bash Read Write Edit Glob Grep AskUserQuestion

`tsk` Docker Configuration Guide

You are helping a user configure `tsk` Docker container images for their project. Follow these steps in order.

Step 1: Gather Project Information

Detect the project's technology stack by checking for these files in the project root. These are `tsk`'s built-in stacks with auto-detection — custom stacks for any language can be defined via `stack_config` in `tsk.toml` (covered in Step 5).

| File | Stack | |------|-------| | `Cargo.toml` | rust | | `go.mod` | go | | `package.json` | node | | `pyproject.toml`, `requirements.txt`, `setup.py` | python | | `pom.xml`, `build.gradle`, `build.gradle.kts` | java | | `rockspec`, `.luacheckrc`, `init.lua` | lua | | None of the above | default |

Also determine the project name from the current directory name.

Tell the user what you detected and ask them to confirm or override. If their stack isn't listed above, let them know they can define a custom stack.

Step 2: Check for Deprecated Dockerfiles

Check if `.tsk/dockerfiles/` exists. If it does, warn the user:

> **Deprecated**: `tsk` no longer supports filesystem-based dockerfiles in `.tsk/dockerfiles/`. Docker customization is now done via `setup` fields in `tsk.toml`. This guide will help you migrate to the new format.

List any files found in `.tsk/dockerfiles/` and note their contents — you will use them to populate the new config.

Step 3: Choose Configuration Location

Ask the user where to put the configuration:

• **Project-level** (`.tsk/tsk.toml`): Checked into version control, shared with the team. Best for project-specific dependencies that all contributors need.
• **User-level** (`~/.config/tsk/tsk.toml`): Personal settings, not shared. Best for machine-specific paths, personal preferences, or settings across multiple projects.

If the user picks user-level, config goes under `[project.<project-name>]` in `~/.config/tsk/tsk.toml`. If project-level, config goes at the top level of `.tsk/tsk.toml`.

Step 4: View the Current Docker Build

Run this command and show the output to the user:

tsk docker build --dry-run

Explain to the user: this shows the complete Dockerfile that `tsk` generates with all layers resolved. Look for comments like `# Stack layer`, `# Project layer`, and `# Agent layer` to see where each `setup` field injects content. The next step will help them add the right customizations.

Step 5: Populate Configuration

Based on the project analysis, write the `tsk.toml` configuration. Use the layer reference below to decide what goes where.

`tsk` Docker Layer Architecture

`tsk` builds container images using 4 layers, assembled in this order:

1. Base layer    — Ubuntu 25.10, git, build-essential, ripgrep, Python 3, uv, podman
2. Stack layer   — Language runtime and tools (e.g., Go, Rust, Node.js)
3. Project layer — Project-specific system dependencies
4. Agent layer   — AI agent installation (Claude, Codex)

You customize layers 2-4 via `tsk.toml`:

| Config field | Layer | Purpose | |---|---|---| | `stack_config.<stack>.setup` | Stack (2) | Language tooling, compilers, package managers | | `setup` | Project (3) | Project-specific apt packages, system libraries, custom tools | | `agent_config.<agent>.setup` | Agent (4) | Agent-specific setup (rarely needed) |

Each `setup` field contains raw Dockerfile commands (`RUN`, `ENV`, `COPY`, etc.) that get injected into the generated Dockerfile at the corresponding layer position. Setup commands run as the `agent` user by default. Use `USER root` to switch to root for operations that require it (e.g., `apt-get`), and always switch back to `USER agent` afterwards.

Built-in Stacks (What's Already Included)

`tsk` has built-in stack layers. You only need `stack_config` if the built-in is insufficient.

**rust**: Rust stable via rustup, `CARGO_TARGET_DIR=/home/agent/.cargo/target`

**go**: Go 1.25.0, `GOPATH=/home/agent/gopath`, `CGO_ENABLED=0`

**node**: Node.js LTS, npm, pnpm, yarn, typescript, ts-node, nodemon, eslint, prettier, jest, npm-check-updates. `NODE_ENV=development`

**python**: uv venv at `/home/agent/.venv`, pytest, pip, black, ruff, ty, mypy, poetry

**java**: OpenJDK 17, Maven, Gradle. Maven `settings.xml` and Gradle `gradle.properties` are pre-configured to route through the `tsk` proxy

**lua**: LuaJIT, Lua 5.1 dev libs, Neovim, stylua, LuaRocks with luacheck/busted/luassert/luafilesystem/nlua

**default**: Empty (base layer only)

Base Layer (Always Present)

Every container includes: Ubuntu 25.10, git, git-lfs, build-essential, curl, jq, just, ripgrep, sudo, Python 3, uv, podman (for DIND), and an `agent` user (UID 1000).

Configuration Format

**Project-level** (`.tsk/tsk.toml`):

# Project-specific dependencies (injected at the project layer)
setup = '''
USER root
RUN apt-get update && apt-get install -y libssl-dev pkg-config cmake
USER agent
'''

# Override or extend the stack layer
[stack_config.rust]
setup = '''
RUN cargo install cargo-nextest sccache
ENV RUSTC_WRAPPER=sccache
'''

**User-level** (`~/.config/tsk/tsk.toml`):

# Default settings for all projects
[defaults]
memory_gb = 16.0
cpu = 8

# Per-project overrides
[project.my-project]
stack = "rust"
setup = '''
USER root
RUN apt-get update && apt-get install -y libssl-dev pkg-config
USER agent
'''

[project.my-project.stack_config.rust]
setup = '''
RUN cargo install cargo-nextest
'''

Common Examples

**Rust project needing system libraries:**

setup = '''
USER root
RUN apt-get update && apt-get install -y \
    libssl-dev pkg-config cmake protobuf-compiler
USER agent
''