invoice

<objective> Generate a professional PDF invoice by combining client billing data with line item details, then output a ready-to-send PDF. </objective>

<usage>

Invocation

/invoice <client> [description] [amount] [options]

Examples

# Full inline — generates immediately
/invoice validcodes "AI Training Pack" 7500 --net 15

# Just client — prompts for line items and terms
/invoice validcodes

# With notes
/invoice validcodes "Sprint Phase 1" 40000 --net 1 --notes "50% upfront per SOW"

# Hourly — interactive mode for multiple line items
/invoice acme --hourly

# Custom quantity
/invoice validcodes "Advisory Call" 300 --quantity 4 --net 15

Arguments

</usage>

<configuration>

Required Setup

Paths

The skill needs these directories configured for your environment:

The generator script, HTML template, and default logo are bundled with this skill.

Client YAML Schema

Create one YAML file per client in your clients directory:

# clients/acme.yaml
name: "Acme Corporation"
aliases: [acme, acme-corp]
default_net: 30

Sender Info

Create a sender.yaml file in the same directory as your client YAML files:

# clients/sender.yaml
name: "Your Name"
address_1: "123 Main St"
address_2: "City, ST 12345"

The generator reads sender from the temp config to populate the "Pay to" block on invoices.

Dependencies

The generator requires Python packages installed via uv:

uv run --with weasyprint --with pyyaml --with jinja2 python3 generate-invoice.py <config.yaml>

</configuration>

<process>

Step 1: Resolve Client

1. Read the first argument as the client identifier
2. Glob all YAML files in the clients directory
3. For each file, check:

- Filename (without .yaml) matches the arg (case-insensitive) - The aliases array contains the arg (case-insensitive)

1. If no match found, list available clients and ask the user to choose
2. Load the matched client's billing info

Step 2: Collect Invoice Details

For any fields not provided as arguments, prompt the user:

1. Description — What is the line item? (e.g., "AI Training Pack", "Sprint Phase 1")
2. Amount — Total amount in USD
3. NET terms — Use --net arg, or client's default_net, or fall back to 15
4. Quantity — Default 1 unless specified
5. Notes — Optional, use --notes arg or ask if user wants to add any

For --hourly mode, interactively collect multiple line items:

• Prompt for each: description, hours, rate
• Calculate amount as hours × rate
• Keep asking "Add another line item?" until done

Step 3: Determine Invoice ID

1. Scan the output directory for existing PDF files matching invoice-#*.pdf
2. Extract the highest invoice number N
3. Use N+1 as the new invoice ID
4. If no existing invoices, start at 1

Step 4: Generate Invoice

1. Compute invoice date (today) and due date (today + NET days)
2. Format dates as MM/DD/YYYY
3. Create a client slug from the YAML filename (used in PDF filename)
4. Write a temporary YAML config file combining client info + sender info + line items (load sender.yaml from the clients directory)
5. Determine the skill directory (where generate-invoice.py lives)
6. Check for a logo override in the clients directory's parent — if it exists, use --logo flag; otherwise use the bundled default
7. Run the generator:

uv run --with weasyprint --with pyyaml --with jinja2 python3 \
  <skill-dir>/generate-invoice.py <temp-config.yaml> \
  --output-dir <output-dir> \
  [--logo <custom-logo>]

1. Delete the temporary YAML config

Step 5: Review and Commit

1. Open/display the generated PDF for the user to review
2. Report: invoice number, client, amount, due date, file path
3. Ask: "Does this look right? Commit?"
4. If approved, stage and commit with message:

`` feat: Generate <client> invoice #N ($X,XXX) ``

1. If changes needed, go back and adjust

</process>

<reference_files>

• generate-invoice.py — PDF generator script (bundled with this skill)
• invoice-template.html — Jinja2 HTML template (bundled with this skill)
• logo.png — Default logo (bundled with this skill)
• INVOICE-TEMPLATE-SPEC.md — Full design spec for the template layout

</reference_files>