skills-marketplace/plugins/invoice-prep-test/skills/invoice-prep-test/SKILL.md

name

description

invoice-prep-test

TEST VERSION of 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. This variant requests the Tempo API token via the plugin's install-time configuration instead of a .env file. 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 (test — plugin userConfig for Tempo token)

This is a test copy of the invoice-prep skill. It exists to check whether a credential declared in the plugin's userConfig (prompted for when the plugin is installed/enabled) actually reaches this skill's script as an environment variable — CLAUDE_PLUGIN_OPTION_TEMPO_API_TOKEN — when the script is run via the Bash tool. Everything else about the skill is unchanged from invoice-prep.

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

Variable	Purpose	Where it comes from
Tempo API Token	Fetch worklogs from Tempo	Prompted at plugin install/enable time (userConfig.tempo_api_token). Falls back to TEMPO_API_TOKEN in .env if the plugin-provided value isn't available.
JIRA_BASE_URL	Resolve the user's account ID	.env file in the project root
JIRA_EMAIL	Identifies whose timesheets to read	.env file in the project root
JIRA_API_TOKEN	Authenticate with Jira	.env file in the project root

Copy .env.example to .env in this skill folder (or the project root) and fill in the three Jira values. The Tempo token should NOT go in .env for this test — it's meant to come from the plugin's install-time prompt, so we can see whether that mechanism actually works.

The script prints which source it used for the Tempo token (CLAUDE_PLUGIN_OPTION_TEMPO_API_TOKEN vs .env fallback) — check that line in the output to see the test result.

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/.

Report the printed "Tempo token source" line back to the user along with the results — that's the point of this test.

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.