Invoice Engine

Generate, manage, and track professional invoices with client onboarding, customizable payment terms, recurring billing, automated overdue reminders, and fin...

Security Scan

An instruction-only invoicing skill whose requirements and instructions are consistent with its stated purpose; it stores invoice and client data locally (YAML) and does not request credentials or install code.

Purpose & Capability

The name/description (invoicing, client onboarding, recurring billing, reminders) matches the SKILL.md content. The skill is zero-dependency and uses local YAML files for clients and invoices, which is coherent with an agent-based invoicing tool.

Instruction Scope

All instructions stay within invoicing: building invoices, onboarding clients, managing a ledger, and scheduling reminders. Two points to note: (1) it instructs the agent to maintain client PII (names, emails, tax IDs, addresses) in workspace YAML files — this is expected for invoicing but has privacy implications, and (2) 'overdue automation' and 'email reminders' are referenced but the skill does not define how to send emails or which external mail/scheduling service to use, leaving implementation up to the agent (not inherently malicious, but ambiguous).

Install Mechanism

There is no install spec and no code files — the skill is instruction-only, so nothing is downloaded or written by an installer. This is the lowest-risk install profile.

Credentials

The skill declares no required environment variables, no credentials, and no config paths. That is proportional to an instruction-only invoicing assistant. It does reference external payment methods (Stripe, PayPal, bank transfer, Bitcoin) in templates, but it does not request those service credentials; if you later supply payment-provider credentials to integrate them, that would be an external step not declared by the skill.

Persistence & Privilege

The skill expects to write and maintain YAML files (clients.yaml, invoices.yaml) in the agent workspace — persistent storage of PII and financial data. It does not request system-wide privileges or 'always:true' presence; agent autonomous invocation is the default and not a special privilege here.

Assessment

This is an instruction-only invoicing skill that appears to be what it says: it will create and manage local YAML files containing client and invoice data (including PII and tax IDs). Before installing or using it: (1) be aware your workspace will store sensitive client data — ensure those files are saved only where you expect them and consider encrypting/backing them up appropriately; (2) the skill mentions sending reminders and payment links but does not include configured email or payment integrations — you'll need to provide or connect those services separately, and only supply API keys or credentials if you trust the integration and restrict their scope; (3) review any external links in the README before clicking or entering payment information (marketing/context-pack links are present); and (4) if you need automated outbound actions (email, webhooks, payment charges), explicitly confirm what connector the agent will use and what credentials it will receive. Overall the skill is internally consistent, but treat stored data and any future credential provisioning with normal care.

Invoice Engine — Complete Invoicing & Accounts Receivable

A zero-dependency agent skill for end-to-end invoicing — from quote to payment to reporting.

Quick Start

When the user says "create an invoice" or "bill [client]":

1. Check if client exists in memory (see Client Registry below)
2. If new client → run Client Onboarding
3. Generate invoice using the Invoice Builder
4. Present for review → finalize
5. Track in the Invoice Ledger

---

1. Client Registry

Maintain a YAML client database in your workspace:

# clients.yaml
clients:
  - id: "CLI-001"
    name: "Acme Corp"
    contact: "Jane Smith"
    email: "[e-mail]"
    address:
      line1: "123 Business Ave"
      line2: "Suite 400"
      city: "New York"
      state: "NY"
      zip: "10001"
      country: "US"
    tax_id: "US-EIN-12-3456789"
    payment_terms: "net-30"       # net-15, net-30, net-45, net-60, due-on-receipt, custom
    preferred_currency: "USD"
    default_tax_rate: 0           # 0 for B2B cross-border, local rate for domestic
    notes: "PO required for invoices > $5,000"
    created: "2026-01-15"
    lifetime_revenue: 12500.00
    invoices_sent: 3
    invoices_paid: 2
    avg_days_to_pay: 22

Client Onboarding Checklist

When adding a new client, collect:

• Legal entity name (exactly as on their records)
• Billing contact name + email
• Billing address (full, with country)
• Tax ID / VAT number (if applicable)
• Preferred payment terms
• Currency preference
• Any PO or approval requirements
• Tax-exempt? (if so, get certificate reference)

---

2. Invoice Builder

Invoice Number Format

[PREFIX]-[YEAR].[MONTH].[SEQUENCE]
Example: INV-2026.02.001

Configurable prefix per business line:

• INV = standard invoice
• PRO = proforma / quote
• REC = recurring invoice
• CN = credit note

Invoice Template

When generating an invoice, structure it as:

╔══════════════════════════════════════════════════════════╗
║  [YOUR COMPANY NAME]                                     ║
║  [Address Line 1]                                        ║
║  [City, State ZIP]                                       ║
║  [Country]                                               ║
║  Tax ID: [YOUR TAX ID]                                   ║
╠══════════════════════════════════════════════════════════╣
║                                                          ║
║  INVOICE [NUMBER]                  Date: [ISSUE DATE]    ║
║                                    Due:  [DUE DATE]      ║
║                                                          ║
║  Bill To:                          Payment Terms:        ║
║  [CLIENT NAME]                     [Net-30 / etc.]       ║
║  [Client Address]                                        ║
║  [City, State ZIP]                 PO Number:            ║
║  Tax ID: [CLIENT TAX ID]          [If applicable]        ║
║                                                          ║
╠══════════════════════════════════════════════════════════╣
║  #  │ Description          │ Qty │ Rate    │ Amount     ║
╠═════╪══════════════════════╪═════╪═════════╪════════════╣
║  1  │ [Service/Product]    │  1  │ $X,XXX  │ $X,XXX.XX ║
║  2  │ [Service/Product]    │  3  │ $XXX    │ $X,XXX.XX ║
║  3  │ [Expense passthrough]│  1  │ $XXX    │ $XXX.XX   ║
╠═════╧══════════════════════╧═════╧═════════╧════════════╣
║                              Subtotal:    $XX,XXX.XX     ║
║                              Discount:    -$X,XXX.XX     ║
║                              Tax (X%):    $X,XXX.XX      ║
║                              ─────────────────────────   ║
║                              TOTAL DUE:   $XX,XXX.XX     ║
╠══════════════════════════════════════════════════════════╣
║  Payment Methods:                                        ║
║  • Bank Transfer: [Bank] | Acct: [XXXX] | Routing: [XX] ║
║  • PayPal: [email]                                       ║
║  • Stripe: [payment link]                                ║
║  • Bitcoin: [address] / Lightning: [LNURL]               ║
║                                                          ║
║  Notes: [Custom message / thank you / late fee notice]   ║
╚══════════════════════════════════════════════════════════╝

Line Item Types

• Time-based: Hours × hourly rate (log hours, auto-calculate)
• Fixed fee: Project milestones, retainers
• Quantity-based: Units × unit price
• Expense passthrough: At-cost or with markup %
• Discount line: Negative amount (early payment, volume, loyalty)
• Recurring: Auto-populated from recurring schedule

Tax Handling Decision Tree

Is client in same country as you?
├── YES → Apply local tax rate
│   ├── Client tax-exempt? → Add exemption reference, 0% tax
│   └── Client NOT exempt → Apply standard rate
└── NO → Usually 0% (reverse charge / export)
    ├── Both in EU? → Reverse charge mechanism (0%, note on invoice)
    ├── US interstate? → Check nexus rules
    └── International → 0% with export reference

Discount & Pricing Framework

• Early payment: 2/10 Net 30 (2% discount if paid within 10 days)
• Volume: Tiered pricing (1-10 units = $X, 11-50 = $Y, 51+ = $Z)
• Loyalty: After 6+ invoices, offer 5% ongoing discount
• Bundled: Package multiple services, discount 10-15% vs à la carte
• Seasonal: Q4 premium (+10%), Q1 discount (-5%) if applicable

---

3. Invoice Lifecycle & Status Tracking

Status Flow

DRAFT → SENT → VIEWED → PARTIALLY_PAID → PAID → CLOSED
                  ↓
              OVERDUE → ESCALATED → WRITTEN_OFF
                  ↓
            DISPUTED → RESOLVED → PAID

Invoice Ledger (YAML)

# invoices.yaml
invoices:
  - number: "INV-2026.02.001"
    client_id: "CLI-001"
    status: "sent"
    issue_date: "2026-02-13"
    due_date: "2026-03-15"
    currency: "USD"
    subtotal: 5000.00
    discount: 0
    tax: 0
    total: 5000.00
    amount_paid: 0
    balance_due: 5000.00
    payment_terms: "net-30"
    line_items:
      - description: "AI Integration Consulting — February"
        qty: 20
        rate: 250.00
        amount: 5000.00
    payments: []
    notes: ""
    sent_date: "2026-02-13"
    reminders_sent: 0
    created: "2026-02-13T10:30:00Z"

Payment Recording

When a payment comes in:

payments:
  - date: "2026-03-10"
    amount: 5000.00
    method: "bank_transfer"    # bank_transfer, stripe, paypal, btc, cash, check
    reference: "TXN-ABC123"
    notes: "Paid in full"

Update: amount_paid, balance_due, status (→ paid if balance = 0, → partially_paid if balance > 0)

---

4. Recurring Invoices

Schedule Configuration

recurring:
  - id: "REC-001"
    client_id: "CLI-001"
    description: "Monthly Retainer — AI Ops Support"
    frequency: "monthly"          # weekly, biweekly, monthly, quarterly, annually
    day_of_month: 1               # 1-28 (avoid 29-31 for safety)
    line_items:
      - description: "AI Operations Retainer"
        qty: 1
        rate: 3500.00
    auto_send: true               # false = create as draft
    start_date: "2026-01-01"
    end_date: null                # null = indefinite
    next_invoice: "2026-03-01"
    invoices_generated: 2
    active: true

Recurring Invoice Routine (run on schedule)

1. Check recurring entries where next_invoice <= today and active = true
2. For each: generate invoice from template, assign next number
3. If auto_send = true → mark as sent, notify client
4. If auto_send = false → save as draft, notify user for review
5. Update next_invoice to next occurrence
6. Log in daily memory

---

5. Overdue Management & Collections

Reminder Schedule

Days After Due	Action	Tone
+1 day	Friendly reminder email	"Just a gentle reminder..."
+7 days	Follow-up with invoice attached	"Following up on..."
+14 days	Firm reminder, mention late fee	"This invoice is now 14 days past due..."
+30 days	Final notice before escalation	"Final notice — please remit payment..."
+45 days	Escalate to human (Kalin/Christina)	Flag for personal outreach
+60 days	Consider write-off or collections	Business decision

Reminder Templates

Day +1 (Friendly)

Subject: Friendly reminder — Invoice [NUMBER] due [DATE]

Hi [CONTACT],

Hope all is well! Just a quick reminder that invoice [NUMBER] for [AMOUNT] was due on [DATE].

If you've already sent payment, please disregard this note.

Payment details are on the attached invoice. Let me know if you need anything.

Best,
[YOUR NAME]

Day +14 (Firm)

Subject: Invoice [NUMBER] — 14 days overdue ([AMOUNT])

Hi [CONTACT],

Invoice [NUMBER] for [AMOUNT] is now 14 days past the due date of [DATE].

Per our agreement, a late fee of [X]% may apply to balances outstanding beyond [Y] days.

Could you confirm when we can expect payment? Happy to discuss if there's an issue.

Thanks,
[YOUR NAME]

Day +30 (Final)

Subject: Final notice — Invoice [NUMBER] overdue ([AMOUNT])

Hi [CONTACT],

This is a final reminder that invoice [NUMBER] for [AMOUNT] remains unpaid, now 30 days past the due date.

Please arrange payment within the next 7 business days to avoid further action.

If there's a dispute or issue with this invoice, please let me know immediately so we can resolve it.

Regards,
[YOUR NAME]

Late Fee Calculation

Standard: 1.5% per month on overdue balance (18% APR)
Grace period: 5 business days after due date
Compound: Simple interest (not compound)
Cap: 25% of invoice total (or local legal maximum)

Formula: late_fee = balance_due × (monthly_rate / 30) × days_overdue
Example: $5,000 × (0.015 / 30) × 14 = $35.00

---

6. Financial Reporting

Revenue Dashboard (generate weekly/monthly)

═══ REVENUE SUMMARY — [MONTH YEAR] ═══

Invoiced This Month:      $XX,XXX.XX  ([N] invoices)
Collected This Month:     $XX,XXX.XX  ([N] payments)
Outstanding (not overdue): $XX,XXX.XX  ([N] invoices)
Overdue:                  $XX,XXX.XX  ([N] invoices, avg [X] days late)
Written Off (YTD):        $XX,XXX.XX

Collection Rate:          XX.X%  (collected / invoiced, trailing 90 days)
Avg Days to Pay:          XX days (trailing 90 days)
Avg Invoice Size:         $X,XXX.XX

═══ TOP CLIENTS (by revenue, YTD) ═══
1. [Client] — $XX,XXX  ([N] invoices, avg [X] days to pay)
2. [Client] — $XX,XXX  ([N] invoices, avg [X] days to pay)
3. [Client] — $XX,XXX  ([N] invoices, avg [X] days to pay)

═══ AGING REPORT ═══
Current (not yet due):     $XX,XXX  ([N] invoices)
1-15 days overdue:         $XX,XXX  ([N] invoices)
16-30 days overdue:        $XX,XXX  ([N] invoices)
31-60 days overdue:        $XX,XXX  ([N] invoices)
60+ days overdue:          $XX,XXX  ([N] invoices) ⚠️

═══ MONTHLY TREND ═══
Jan: $XX,XXX ████████████
Feb: $XX,XXX ████████████████
Mar: $XX,XXX ██████████
...

═══ ACTIONS NEEDED ═══
• [N] invoices need reminder emails
• [N] recurring invoices due for generation
• [Client] has disputed INV-XXXX — needs resolution

Key Metrics to Track

• Collection Rate: % of invoiced amount actually collected (target: >95%)
• DSO (Days Sales Outstanding): avg days from invoice to payment (target: <30)
• Overdue Ratio: overdue balance / total outstanding (target: <10%)
• Revenue Concentration: % from top client (flag if >40% — dependency risk)
• MRR from Recurring: recurring invoice total / month

---

7. Credit Notes & Adjustments

When a refund or correction is needed:

credit_note:
  number: "CN-2026.02.001"
  original_invoice: "INV-2026.01.003"
  client_id: "CLI-001"
  reason: "Partial refund — service hours overcharged"
  line_items:
    - description: "Correction: 5 hours overcharged"
      qty: -5
      rate: 250.00
      amount: -1250.00
  total: -1250.00
  issued: "2026-02-13"

Apply credit notes against:

1. The original invoice (reduce balance)
2. Future invoices (credit on account)
3. Direct refund (record refund method + reference)

---

8. Multi-Currency Support

currencies:
  primary: "USD"
  accepted: ["USD", "GBP", "EUR", "BTC"]
  exchange_rates:  # Update weekly or use live rates
    GBP_USD: 1.27
    EUR_USD: 1.08
    BTC_USD: 97500
  conversion_note: "Converted at rate on invoice date. Payment accepted in invoiced currency only."

Rules:

• Always invoice in the client's preferred currency
• Record payments in the currency received
• Convert to primary currency for reporting (use rate on payment date)
• Note exchange rate on invoice if cross-currency
• BTC/Lightning: include both sats and fiat equivalent

---

9. Quote-to-Invoice Pipeline

Quote (Proforma) Template

Same as invoice template but:

• Prefix: PRO- instead of INV-
• Header: "QUOTATION" instead of "INVOICE"
• Add: "Valid until: [DATE]" (typically 30 days)
• Add: "This is not a tax invoice"

Pipeline Flow

QUOTE → ACCEPTED → INVOICE → PAID
  ↓
EXPIRED (auto-expire after validity period)
  ↓
REVISED (new version with changes)

When a quote is accepted:

1. Convert to invoice (change prefix, remove validity notice)
2. Assign invoice number
3. Set payment terms based on client profile
4. Send invoice
5. Archive quote as "converted"

---

10. Edge Cases & Rules

Partial Payments

• Record each payment separately with reference
• Update balance_due after each payment
• On final payment → mark PAID
• If partial + overdue → chase remaining balance only

Disputed Invoices

• Mark status as DISPUTED
• Record dispute reason and date
• Pause reminders during dispute
• Track resolution (adjusted, credit note, or confirmed correct)
• Resume billing after resolution

Void vs Credit Note

• Void: Invoice was sent in error, never should have existed → mark VOIDED, exclude from reports
• Credit Note: Services were delivered but need adjustment → issue CN, include in reports

Tax Invoice Requirements (by region)

• US: No strict format, but include EIN if registered
• UK/EU: Must include VAT number, VAT amount, "reverse charge" note if applicable
• Australia: Must say "Tax Invoice", include ABN, GST amount
• Canada: Include GST/HST number, province-specific rules

Rounding

• Always round line item amounts to 2 decimal places
• Calculate tax on subtotal (not per-line) to avoid penny discrepancies
• Display currency symbol before amount: $1,234.56

Invoice Numbering

• NEVER reuse or skip numbers (tax audit requirement)
• Sequential within each prefix
• If voided, keep the number, just mark status

---

11. Automation Opportunities

Set up cron jobs or heartbeat checks for:

• Generate recurring invoices on schedule
• Send overdue reminders per the schedule above
• Weekly revenue dashboard to owner
• Monthly aging report
• Auto-flag clients with >45 days overdue
• Quarterly review: update exchange rates, review pricing

---

12. Export Formats

When the user needs to export:

• CSV: For spreadsheet / accounting import

  invoice_number,client,date,due_date,total,status,amount_paid,balance
  

• JSON: For API integration or backup
• Markdown table: For quick review in chat
• PDF-ready text: Formatted text block ready for PDF generation tool

---

Commands Reference

Command	Action
"Invoice [client] for [amount/description]"	Create new invoice
"Quote [client] for [service]"	Create proforma
"Show outstanding invoices"	List unpaid invoices
"What's overdue?"	Aging report, overdue only
"Revenue this month"	Monthly revenue dashboard
"Send reminder for [invoice]"	Generate reminder email
"Record payment [invoice] [amount]"	Log payment received
"Recurring: [client] [amount] [frequency]"	Set up recurring invoice
"Credit note for [invoice]"	Issue credit/adjustment
"Client report [name]"	Full client payment history
"Export invoices [format]"	CSV/JSON/Markdown export
"Void [invoice]"	Void an invoice
"Update rates"	Refresh exchange rates