ckb/.agents/skills/invoice-prep/SKILL.md

name

description

invoice-prep

Show what to put on an invoice for a selected month by checking the user's own Tempo timesheets. Lists every Jira project code and the total hours logged against it. Warns if there are missing hours or days with no logged time. TRIGGER when user asks what to put on an invoice, what to invoice, invoice preparation, timesheet summary for invoicing, or similar phrases. Trigger phrases: "what should I put on an invoice", "prepare my invoice", "invoice for [month]", "what to invoice for", "check my TS for invoice".

Invoice Preparation

Use this skill when someone wants to know what project codes and hours to put on their invoice for a given month. It reads their own Tempo worklogs, groups hours by Jira project, and warns about any missing time.

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

Prerequisites

Uses the same credentials as the timesheet-checker — no extra setup needed:

Variable	Purpose
TEMPO_API_TOKEN	Fetch worklogs from Tempo
JIRA_BASE_URL	Resolve the user's account ID
JIRA_EMAIL	Identifies whose timesheets to read
JIRA_API_TOKEN	Authenticate with Jira

All four must be present in the .env file in the project root.

Extracting the month

Convert natural language to YYYY-MM before running:

User says	CLI value
"last month"	Previous calendar month
"this month"	Current calendar month
"June", "June 2026"	2026-06
"May"	2026-05 (current year)

If no month is specified, ask: "Which month should I check? (e.g. last month, June 2026)"

Workflow

Step 1 — Run the script:

python3 {SKILL_DIR}/scripts/run.py \
  --month {YYYY-MM} \
  --output-dir ./timesheet-output

This resolves the user's Jira account, fetches their Tempo worklogs for the full calendar month, groups hours by Jira project code, checks completeness against the Polish working calendar, and writes invoice_prep_{YYYY-MM}.json to ./timesheet-output/.

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

1. A table of project codes and hours — formatted ready to copy onto an invoice. Include every project in the projects array. Do NOT label any project as "non-billable" or omit it from the table — the script already excludes ignored issues; everything remaining is billable:

   | Project | Hours |
   | IAA     | 45.5  |
   | PROJ    | 22.0  |
   

   Below the table, note ignored issues and their hours as a parenthetical: (INTERNAL-1: 40h ignored per config.) — do not mix them into the billable table.

2. The total billable hours from total_billable_hours (not total_logged_hours).

3. If missing_hours > 0: a clear warning showing:

   • How many hours are missing vs the expected total for the month
   • Which specific dates have no logged time (up to 10; if more, show count)
   • Reminder to complete the timesheet before issuing the invoice

4. If total_logged_hours == 0: warn that no hours were found at all for the month.

Guardrails

• Never fabricate or estimate hours. All data comes from Tempo.
• If JIRA_EMAIL is not set, stop and tell the user.
• If any script step fails, show the error and stop.
• Always remind the user that incomplete timesheets will cause Jira compliance failures when the invoice is checked.