skills-marketplace/plugins/timesheet/skills/check-my-timesheet/SKILL.md

name

description

check-my-timesheet

Two behaviours in one skill: (1) CHECK — show the current user's timesheet gaps for a given period. Compares Tempo worklogs against the working calendar and flags missing or partial days. (2) LOG — help the user log time to Tempo. User provides a description or issue key; Claude searches Jira if needed, confirms the entry, then posts it. TRIGGER check when user says: "check my timesheet", "timesheet gaps", "where am I missing hours", "did I log all hours", "show my missing time". TRIGGER log when user says: "log time", "add time entry", "log hours", "report hours", "book time on", "add worklog".

Check My Timesheet

Personal timesheet checker and time logger for the user identified by JIRA_EMAIL.

Prerequisites

All configuration lives in the .env file in the project root:

Variable	Purpose	Default
TEMPO_API_TOKEN	Read and write Tempo worklogs	—
JIRA_BASE_URL	Resolve account ID and search issues	—
JIRA_EMAIL	Identifies whose timesheet to read / who is logging	—
JIRA_API_TOKEN	Authenticate with Jira	—
MY_TIMESHEET_COUNTRY	Country code for public holiday calendar (PL, GB, DE…)	PL
MY_TIMESHEET_HOURS_PER_DAY	Expected working hours per day	8

Setup

Determine SKILL_DIR from the location of this file.

---

Behaviour 1 — Check timesheet gaps

Trigger phrases

"check my timesheet", "timesheet gaps", "where am I missing hours", "did I log all hours", "show my time", "show my missing time"

Workflow

Step 1 — Ask for period. Always ask — never assume a default:

"Which period should I check? (e.g. this week, last week, June 2026, or a date range)"

Convert natural language to YYYY-MM-DD:YYYY-MM-DD:

• "this week" → Monday of current week to yesterday
• "last week" → previous Monday–Friday
• "June 2026" → 2026-06-01:2026-06-30
• "today" → today:today

Step 2 — Run check:

python3 {SKILL_DIR}/scripts/check.py \
  --period {YYYY-MM-DD:YYYY-MM-DD} \
  --output-dir ./timesheet-output

Step 3 — Present results. Read the output JSON and show:

1. Summary: Logged X h / Y h expected (Z working days)

2. If missing_hours == 0: "✓ Timesheet complete for this period."

3. Otherwise, a table of all working days — highlight missing and partial:

   | Date       | Logged | Status   |
   | 2026-06-23 | 8.0 h  | ✓ OK     |
   | 2026-06-24 | 4.0 h  | ⚠ Partial (4h missing) |
   | 2026-06-25 | 0.0 h  | ✗ Missing |
   

4. List only the problem days prominently if there are many OK days.

---

Behaviour 2 — Log time

Trigger phrases

"log time", "add time entry", "log hours", "report hours", "book time on", "add worklog", "log X hours on", "log X hours for"

Workflow

Step 1 — Collect what is needed:

From the user's message extract or ask for:

• Issue — Jira issue key (e.g. IAA-42) or a description to search by
• Hours — number of hours (decimals OK: 1.5 = 1h30m)
• Date — which day to log on (default: today if not mentioned)
• Description — optional note for the worklog

If issue key is not provided but a description is, run a search:

python3 {SKILL_DIR}/scripts/log.py \
  --mode search \
  --query "{description}"

Present the results (up to 5 issues) and ask the user to pick one or confirm. If no results found, ask the user to provide the issue key directly.

Step 2 — Preview (run without --confirmed). Always run the preview step first:

python3 {SKILL_DIR}/scripts/log.py \
  --mode log \
  --issue {KEY} \
  --hours {N} \
  --date {YYYY-MM-DD} \
  --description "{description}"

The script prints the pending worklog and exits without writing anything. If hours exceed MY_TIMESHEET_HOURS_PER_DAY it also prints a ⚠ WARNING line.

Step 3 — Show preview to user and ask for confirmation. Present the full script output including any warnings. Wait for explicit yes/no. Do NOT proceed without explicit confirmation.

Step 4 — Log (only after yes, with --confirmed):

python3 {SKILL_DIR}/scripts/log.py \
  --mode log \
  --issue {KEY} \
  --hours {N} \
  --date {YYYY-MM-DD} \
  --description "{description}" \
  --confirmed

Step 5 — Report result. Show the worklog ID and a confirmation message. Offer to check the timesheet again to verify the entry is reflected.

---

Guardrails

• Never log time without explicit user confirmation.
• Always run the preview step first — the --confirmed flag must only be added after the user says yes.
• If the preview shows a ⚠ WARNING (hours exceed daily limit), make sure the user acknowledges it before confirming.
• If my_timesheet.md is missing, stop and show the user the template.
• If JIRA_EMAIL is not set, stop and ask the user to set it in .env.
• If any script step fails, show the error and stop.
• Do not guess the issue key — always search or ask if unsure.