invoice - SKILL.md Agent Skill

name: invoice description: Generate professional PDF invoices with line items, tax calculations, and 1404 branding for client billing user-invocable: true metadata: { "openclaw": { "emoji": "🧾", "requires": { "bins": ["python3"], "pip": ["reportlab"] } } }

When to use

Use this skill when the user needs to generate a professional invoice PDF. Common scenarios:

Monthly retainer invoices: recurring billing for ongoing client engagements
Project-based invoices: milestone payments, final deliverable billing
Hourly billing: time-tracked invoices with hours and rates
Expense reports: reimbursable expenses with line items
Partial invoices: progress billing on large construction/manufacturing projects

Steps

Gather requirements from the user: client info, line items, payment terms, any special notes.
Build a JSON config object with this structure:

{
  "output_path": "/absolute/path/to/invoice.pdf",
  "branding": {
    "primary_color": [26, 26, 46],
    "accent_color": [233, 69, 96],
    "company_name": "1404 Labs",
    "company_address": "123 Main Street\nSuite 400\nAnytown, ST 12345",
    "company_email": "billing@1404labs.com",
    "company_phone": "(555) 123-4567",
    "company_website": "1404labs.com"
  },
  "invoice": {
    "number": "INV-2026-0042",
    "date": "February 7, 2026",
    "due_date": "March 9, 2026",
    "po_number": "PO-12345",
    "client": {
      "name": "ACME Construction",
      "contact": "Jane Smith",
      "address": "456 Builder Ave\nIndustrial Park\nMetroville, ST 67890",
      "email": "jane@acmeconstruction.com"
    },
    "line_items": [
      {
        "description": "Web Application Development - Phase 2",
        "quantity": 1,
        "rate": 35000.00,
        "amount": 35000.00
      },
      {
        "description": "UI/UX Design Services (40 hrs @ $150/hr)",
        "quantity": 40,
        "rate": 150.00,
        "amount": 6000.00
      }
    ],
    "subtotal": 41000.00,
    "tax_rate": 0.0,
    "tax_amount": 0.00,
    "total": 41000.00,
    "amount_paid": 0.00,
    "balance_due": 41000.00,
    "payment_terms": "Net 30",
    "payment_methods": "Wire Transfer or ACH\nBank: First National Bank\nRouting: 123456789\nAccount: 987654321",
    "notes": "Thank you for your business. Please reference invoice number on all payments."
  }
}

Write the JSON config to a temporary file:

cat > /tmp/invoice_config.json << 'JSONEOF'
{ ... your config ... }
JSONEOF

Run the generator script:

python3 {baseDir}/generate.py /tmp/invoice_config.json

Report the output path printed by the script to the user.
Clean up the temporary JSON file.

JSON Config Reference

Field	Type	Required	Description
`output_path`	string	yes	Absolute path for the output PDF
`branding`	object	no	Branding overrides (see below)
`invoice`	object	yes	Invoice data

Branding Object

Field	Type	Default	Description
`primary_color`	[R,G,B]	[26, 26, 46]	Dark navy primary
`accent_color`	[R,G,B]	[233, 69, 96]	Red accent
`company_name`	string	"1404 Labs"	Company name on invoice
`company_address`	string	""	Company address (use \n for line breaks)
`company_email`	string	"billing@1404labs.com"	Billing email
`company_phone`	string	""	Phone number
`company_website`	string	"1404labs.com"	Website

Invoice Object

Field	Type	Required	Description
`number`	string	yes	Invoice number (e.g., "INV-2026-0042")
`date`	string	yes	Invoice date
`due_date`	string	yes	Payment due date
`po_number`	string	no	Client purchase order number
`client`	object	yes	Client billing info (see below)
`line_items`	array	yes	Array of line item objects
`subtotal`	number	yes	Sum of all line item amounts
`tax_rate`	number	no	Tax rate as decimal (0.08 = 8%)
`tax_amount`	number	no	Calculated tax amount
`total`	number	yes	Grand total including tax
`amount_paid`	number	no	Amount already paid (default: 0)
`balance_due`	number	yes	Remaining balance
`payment_terms`	string	no	Terms (e.g., "Net 30")
`payment_methods`	string	no	Payment instructions
`notes`	string	no	Additional notes

Client Object

Field	Type	Required	Description
`name`	string	yes	Client company or individual name
`contact`	string	no	Contact person name
`address`	string	no	Billing address (use \n for line breaks)
`email`	string	no	Client email

Line Item Object

Field	Type	Required	Description
`description`	string	yes	Item description
`quantity`	number	yes	Quantity (can be hours, units, or 1 for flat fee)
`rate`	number	yes	Per-unit rate
`amount`	number	yes	Line total (quantity * rate)

Examples

Monthly Retainer Invoice

{
  "output_path": "/home/holden/outputs/inv_2026_0042.pdf",
  "invoice": {
    "number": "INV-2026-0042",
    "date": "February 1, 2026",
    "due_date": "March 3, 2026",
    "client": {
      "name": "BuildRight Manufacturing",
      "contact": "Tom Richardson",
      "address": "789 Factory Road\nIndustrial District\nManufacturing City, TX 75001"
    },
    "line_items": [
      {
        "description": "Monthly Software Development Retainer - February 2026",
        "quantity": 1,
        "rate": 12500.00,
        "amount": 12500.00
      },
      {
        "description": "Cloud Infrastructure & Hosting",
        "quantity": 1,
        "rate": 850.00,
        "amount": 850.00
      }
    ],
    "subtotal": 13350.00,
    "tax_rate": 0.0,
    "tax_amount": 0.00,
    "total": 13350.00,
    "amount_paid": 0.00,
    "balance_due": 13350.00,
    "payment_terms": "Net 30",
    "notes": "Retainer covers up to 80 development hours. Additional hours billed at $175/hr."
  }
}

Project Milestone Invoice

{
  "output_path": "/home/holden/outputs/inv_2026_0043.pdf",
  "invoice": {
    "number": "INV-2026-0043",
    "date": "February 7, 2026",
    "due_date": "February 21, 2026",
    "po_number": "PO-ACME-2026-15",
    "client": {
      "name": "ACME Construction",
      "contact": "Jane Smith",
      "address": "456 Builder Ave\nMetroville, ST 67890",
      "email": "accounts@acmeconstruction.com"
    },
    "line_items": [
      {
        "description": "Milestone 2: Core Development Complete (per SOW dated Jan 15, 2026)",
        "quantity": 1,
        "rate": 30000.00,
        "amount": 30000.00
      },
      {
        "description": "Change Order #1: Additional API endpoints (approved Jan 28)",
        "quantity": 12,
        "rate": 175.00,
        "amount": 2100.00
      },
      {
        "description": "Third-party API license (pass-through)",
        "quantity": 1,
        "rate": 500.00,
        "amount": 500.00
      }
    ],
    "subtotal": 32600.00,
    "tax_rate": 0.0825,
    "tax_amount": 2689.50,
    "total": 35289.50,
    "amount_paid": 0.00,
    "balance_due": 35289.50,
    "payment_terms": "Net 15",
    "payment_methods": "Wire Transfer or ACH\nBank: First National Bank\nRouting: 123456789\nAccount: 987654321",
    "notes": "Sales tax applied per Texas state requirements. Please reference PO and invoice number on payment."
  }
}

Constraints

Output format is PDF only (use the spreadsheet skill for editable billing data)
Line item amounts should be pre-calculated (quantity * rate); the script does not compute them
Subtotal, tax, and total should be pre-calculated and consistent
The output directory must already exist
The script requires reportlab to be installed (pip install reportlab)
Colors must be RGB arrays with values 0-255
Currency is formatted as USD ($); no multi-currency support
Page size is US Letter (8.5" x 11")
Maximum ~25 line items per page before overflow (multi-page supported)