Invoice skill

Create, edit, and export styled invoice PDFs through a split-pane browser editor. Claude drives the workflow by writing workspace JSON files; the editor hot-reloads the preview. Headless PDF export runs without opening a browser.

1. Setup

Install dependencies and the Chromium browser used for PDF export:

npm install
npx playwright install chromium

Scaffold the workspace directory (creates sample profile, invoice, and template):

tsx skills/invoice/scripts/launch.ts

This prints:

Workspace ready at ./workspace.
Run "npm run editor" and open http://localhost:4317 to edit and preview.
Export headlessly with: npm run export -- <invoice-name>

To use a custom workspace path, set INVOICE_WORKSPACE:

INVOICE_WORKSPACE=/path/to/ws tsx skills/invoice/scripts/launch.ts

2. Launch the editor

npm run editor

Open http://localhost:4317 in a browser. The UI has two panes:

• Left — tabbed controls: Data (invoice fields), Style (colours, fonts, page size), Code (raw HTML/CSS template editor).
• Right — live preview that hot-reloads whenever workspace files change.

Clicking Export PDF in the editor exports the current invoice and saves it to workspace/output/<invoice-name>.pdf.

3. Workspace file contract

workspace/
  profiles/
    <name>.json          # sender profile (company, address, logo)
  invoices/
    <name>.json          # invoice data (client, items, dates)
  templates/
    <name>/
      template.html      # Handlebars HTML template
      template.css       # template stylesheet
      style.json         # style variables (colours, fonts, page size)
  output/
    <name>.pdf           # generated PDFs (written by export)

The classic template is seeded by scaffoldWorkspace. Add more templates by creating additional subdirectories under templates/.

4. JSON schemas

All files are validated against these schemas at load time. Unknown fields are ignored; all fields listed here are required unless marked optional.

workspace/invoices/<name>.json — InvoiceSchema

workspace/profiles/<name>.json — ProfileSchema

workspace/templates/<name>/style.json — StyleSchema

5. Filling invoice data as Claude

When the user asks to create or update an invoice (e.g. "invoice Beta Corp for 10 h design at €90"):

1. Choose an existing profile from workspace/profiles/ (or create one if none exists).
2. Choose a template from workspace/templates/ (default: classic).
3. Write or update workspace/invoices/<name>.json following InvoiceSchema exactly.

Example invoice file workspace/invoices/beta-design.json:

{
  "profile": "acme",
  "template": "classic",
  "number": "INV-001",
  "client": {
    "name": "Beta Corp",
    "address": "123 Client St, London",
    "email": "accounts@beta.example"
  },
  "items": [
    { "description": "Design work", "quantity": 10, "rate": 90 }
  ],
  "issueDate": "2026-06-29",
  "dueDate": "2026-07-29",
  "notes": "",
  "taxRate": 0
}

If the editor is running at http://localhost:4317, it hot-reloads the preview automatically when the file is saved. Tell the user to refresh the browser tab if the preview does not update immediately.

To create a new sender profile, write workspace/profiles/<name>.json following ProfileSchema.

6. Export to PDF

Export headlessly without opening a browser:

npm run export -- <invoice-name>

For example:

npm run export -- beta-design

The command prints the output path when done, e.g.:

Exported workspace/output/beta-design.pdf

The PDF is saved to workspace/output/<invoice-name>.pdf.