explain-dataset-ess

Helps users of the Timefold Employee Shift Scheduling (ESS) model understand an optimized schedule by fetching and interpreting the dataset via the API. Use this skill whenever someone asks why shifts

SKILL.md

GitHub

Model context: Employee Shift Scheduling (ESS)

Terminology

Generic term ESS term
Work item / work unit shift
Resource employee
Mandatory work mandatory shift
Optional work optional shift
Required capability skill (e.g. C300, PM)
Capacity constraint employment contract (max hours/week)

Model-specific configuration

Always set these before running any script.

MODEL=employee-shift-scheduling
MODEL_API_URL=https://app.timefold.ai/api/models/employee-scheduling/v1
COLLECTION=/schedules
OPENAPI_URL=https://app.timefold.ai/openapis/employee-scheduling/v1

Scripts

Scripts live in the sibling skill explain-dataset-shared, in its scripts/ directory. Anchor every path on this skill's own directory, not on the working directory. The working directory is the user's project, and these skills are installed somewhere else.

In Claude Code, ${CLAUDE_SKILL_DIR} is substituted with this skill's directory. If your agent leaves the placeholder unresolved, replace it with the absolute directory that holds this SKILL.md.

$PY is the Python runner that the shared skill's runtime check selects (uv run, python3, or python). Run that check before the first script call.

The variables in the block below are placeholders. Write their values out in every command you run, with the runner and the absolute script path in full, for example uv run /abs/path/to/explain-dataset-shared/scripts/summarize.py --model-api-url https://... --model .... Each command starts a new shell, so a variable that an earlier command set is gone. And in zsh, the default shell on macOS, $PY with the value uv run stays one word, so the command is not found.

SKILL_DIR=${CLAUDE_SKILL_DIR}
SHARED=$SKILL_DIR/../explain-dataset-shared
SCRIPTS=$SHARED/scripts
PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT:-$SKILL_DIR/../..}

$PY $SCRIPTS/summarize.py             --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID [--tenant ID]
$PY $SCRIPTS/list_unassigned.py       --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID [--recommendations]
$PY $SCRIPTS/resource_metrics.py      --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID [--sort unprefs|overtime|hours|visits|name]
$PY $SCRIPTS/work_details.py          --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID --work-ids "shift-001"
$PY $SCRIPTS/work_details.py          --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID --resource "EMP-001"
$PY $SCRIPTS/score_violations.py      --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID [--type hard|medium|soft]
$PY $SCRIPTS/score_justifications.py  --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID [--samples 3]
$PY $SCRIPTS/score_justifications.py  --model-api-url $MODEL_API_URL --model $MODEL --dataset-id ID --resource "EMP-001"

$SHARED also carries the version stamp and, in a plugin install, $PLUGIN_ROOT carries the plugin manifest. The report metadata needs both. Keep the two variables set.

Documentation

ESS-specific notes

  • Mandatory vs optional is not a tag on the shift. Each shift has a priority (1-10), and whether a given priority counts as mandatory or optional is set per dataset in globalRules.unassignedShiftRule.priorityWeights, which maps priority levels to a MANDATORY or OPTIONAL assignment. When you need to tell which unassigned shifts are actually mandatory (a real bottleneck) versus optional (expected leftover capacity), read that mapping from the dataset's own input rather than assuming a fixed priority threshold. See Mandatory and optional shifts.

Full instructions

Read and follow: $SHARED/SKILL.md