skills-marketplace/plugins/ivona/skills/timesheet-checker/SKILL.md

name

description

timesheet-checker

Check timesheet completion for a given period by pulling Tempo worklogs for all reporters found in Tempo (not just those in employees.md). Flags anyone missing from employees.md and asks the user to add them. Requires TEMPO_API_TOKEN. Checks against the Polish working calendar and 8h/day minimum. Produces a completion report ranked by missing hours. TRIGGER this skill automatically whenever the user mentions checking, reviewing, or auditing timesheets or timesheet completion — especially when they mention a period like last week, last month, or a date range. Trigger phrases include: "check timesheets", "timesheet completion", "review timesheets", "who hasn't logged hours", "timesheet audit", "check logged hours", "hours reported", or any message asking about timesheet status or missing hours.

Timesheet Checker

Use this skill when someone needs to know if employees have completed their timesheets for a given period. It pulls worklogs from Tempo, computes each person's completion against the Polish working calendar, and ranks employees by missing hours.

In Claude Code, you run the full pipeline automatically. The user provides a period — you handle everything else.

Prerequisites

This skill requires four credentials. The easiest way to provide them is a .env file — copy .env.example in the skill folder and fill in the values:

cp {SKILL_DIR}/.env.example {SKILL_DIR}/.env
# then edit {SKILL_DIR}/.env

Or place the .env file in the working directory (where you run Claude Code) — that takes priority over the skill folder.

If the user prefers environment variables they can still use export, but the .env file removes the need to do that every session.

The four credentials:

Variable	What it is	Where to get it
TEMPO_API_TOKEN	Tempo read token	Tempo → Settings → API Integration
JIRA_BASE_URL	Your Atlassian URL	The URL you use to open Jira
JIRA_EMAIL	Your Jira login email	Your Atlassian account email
JIRA_API_TOKEN	Jira personal API token	id.atlassian.com → Security → API tokens

JIRA_BASE_URL, JIRA_EMAIL, and JIRA_API_TOKEN are used to resolve employee email addresses to Jira account IDs before querying Tempo. TEMPO_API_TOKEN is used to pull the actual worklogs.

Setup

Determine SKILL_DIR from the location of this file. Set the output directory to ./timesheet-output/ in the current working directory. Create it if it does not exist.

Load First

Read these reference files:

1. The employees config — check ./employees.md in the current working directory first; if not present, fall back to {SKILL_DIR}/references/employees.md. Tell the user which one is being used.
2. {SKILL_DIR}/references/output-format.md — the structure of timesheet_data.json and the final report.

Extracting the period

The user may express the period in various ways. Convert to the CLI format before running:

User says	CLI value	End date
"last week"	last-week	Last Friday
"last month"	last-month	Last day of previous month
"last year"	last-year	31 December of previous year
"yesterday"	yesterday	Yesterday
"this week", "current week"	current-week	Yesterday
"this month", "current month"	current-month	Yesterday
"this year", "current year"	current-year	Yesterday
"June", "June 2026"	2026-06-01:2026-06-30	Explicit
Explicit dates	YYYY-MM-DD:YYYY-MM-DD	Explicit

For current-* periods the end date is always yesterday — the current in-progress day is never included. If a user asks for "current week" on a Monday (the week only started today), there are no past working days yet; note this to the user.

If the user has not specified a period, ask: "Which period should I check? (e.g. last week, this month, yesterday, or a date range)"

Workflow

Step 1 - Fetch and compute. Run this command with bash:

python3 {SKILL_DIR}/scripts/preprocess.py \
  --period {period} \
  --output-dir ./timesheet-output

This fetches Polish public holidays from date.nager.at, computes working days, pulls all Tempo worklogs for the period, and writes timesheet_data.json to ./timesheet-output/.

Step 2 - Interpret. Read ./timesheet-output/timesheet_data.json. Note:

• Any employee with reported_hours: 0 — this may mean vacation, sick leave, or forgotten logging. Mention these explicitly.
• If the period end date is today or in the future, the period is still open — note this so the user knows the data is partial.
• The overall completion percentage and how many employees have gaps.
• Unknown reporters: If unknown_reporters is non-empty, show the user a table of those people (name, email, hours logged) and ask them to add the missing employees to employees.md. Then continue with Steps 3–4 using only the known employees, noting that the report excludes the unknown reporters until they are added.

Step 3 - Generate report. Run this command with bash:

python3 {SKILL_DIR}/scripts/postprocess.py \
  --data ./timesheet-output/timesheet_data.json \
  --output-dir ./timesheet-output

This writes timesheet_report.md.

Step 4 - Present results. Show the user:

• The summary block (expected / reported / overall completion %).
• The full employee table from the report.
• Any notable observations from Step 2.
• "Full report saved to ./timesheet-output/timesheet_report.md."

Guardrails

• Never invent or estimate hours. All data comes from Tempo.
• Working days are computed from the Polish public holidays API — do not hardcode holiday dates.
• If TEMPO_API_TOKEN is not set, stop and ask the user for it. Do not proceed without it.
• If any script step fails, show the error and stop. Do not proceed with partial output.