c9336941ac
Add four skills for Tempo/KSeF timesheet and invoice workflows: - check-my-timesheet: show/log the current user's Tempo time entries - timesheet-checker: audit timesheet completion across all reporters - invoice-checker: pull KSeF invoices, check contractors + MF white list - invoice-prep: summarize Tempo hours per Jira project for invoicing Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
115 lines
5.8 KiB
Markdown
115 lines
5.8 KiB
Markdown
---
|
||
name: timesheet-checker
|
||
description: >
|
||
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](https://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:
|
||
|
||
```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:
|
||
|
||
```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.
|