agentleFS
emtcmcaemtcmca/claude-for-legal-billing/skills/invoice-generate/SKILL.md

invoice-generate

Skill1 starsChanged 3 months agoMITView on GitHub

Generate a printable invoice exhibit from approved time entries for a client. Produces a Markdown file formatted as supporting documentation to attach to a client invoice. Use when billing period closes and entries have been approved in wip-review.

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 4 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If no client-slug provided: list clients with approved entries and ask which one.

    line 42
  2. Distinctive:

    Read the register through the validator, not by hand: Run:

    line 50
  3. Distinctive:

    Do not recompute them and do not carry figures forward from earlier in the conversation.

    line 58
  4. Very specific:

    If scripts/register-read.ps1 is not present, this is an install predating it.

    line 65
  5. Very specific:

    Read [billing_data_path]/time-register.yaml.

    line 70
  6. Very specific:

    If no entries match: "No approved entries found for [client] in this period.

    line 75
  7. Very specific:

    Read [billing_data_path]/invoice-register.yaml.

    line 86
  8. Distinctive:

    If retainer balance would go negative, warn:

    line 108
  9. Very specific:

    Write the invoice to [billing_data_path]/invoices/[invoice-number].md:

    line 113
  10. Very specific:

    Check config for Activity log on invoice: enabled.

    line 203
  11. Very specific:

    If Activity log on invoice: disabled (or the setting is absent from config), skip this step entirely.

    line 222
  12. Distinctive:

    Delete or undo issued invoices — contact billing counsel if a correction is needed after issuance

    line 266

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/billing-legal:invoice-generate

When this runs

Billing period has closed. Entries have been reviewed and approved via /billing-legal:wip-review. Attorney is ready to generate a supporting invoice document.

Instructions

Preflight - read /billing-legal:billing-guardrails first. It carries the approval gate, the append-only record rule, UTBMS field discipline, and the boundary on what this plugin records rather than decides. Where it conflicts with the steps below, the stricter rule wins.

1. Read config

Read ~/.claude/plugins/config/claude-for-legal/billing/CLAUDE.md. Get:

  • billing_data_path
  • Firm name
  • Billing address
  • Billing email
  • Invoice prefix
  • Next invoice number
  • Task codes setting

2. Determine scope

Parse $ARGUMENTS:

  • First token: required <client-slug>
  • --period YYYY-MM or --period YYYY-MM to YYYY-MM: restrict to entries in that month or range (default: all approved entries for the client)
  • --matter <slug>: restrict to one matter

If no client-slug provided: list clients with approved entries and ask which one. If that list is empty, do not present an empty menu or a question with nothing to choose from. Say: "No client has approved entries ready to invoice. Run /billing-legal:wip-review to approve pending time, or /billing-legal:billing-report --wip to see what is outstanding." Then stop. This is the same condition the <client-slug> branch reports; both paths end the same way.

3. Load entries and client info

Read the register through the validator, not by hand. Run:

powershell -NoProfile -NonInteractive -File "[billing_data_path]/scripts/register-read.ps1" -Client [client-slug]

It resolves the data path from config, confirms the register exists, parses every entry, checks that each amount equals hours x rate, and emits JSON with per-status totals. Use its numbers. Do not recompute them and do not carry figures forward from earlier in the conversation.

  • Exit 2: the register is absent. Stop, report the path it printed, write nothing.
  • Exit 3: it parsed but failed an invariant. Show the errors array and stop before any write. A register whose arithmetic does not hold has been edited by something other than this plugin.
  • Exit 4: config missing or still holds placeholders. Direct to /billing-legal:cold-start-interview.

If scripts/register-read.ps1 is not present, this is an install predating it. Say so, then fall back to reading the file directly under the rule below.

If time-register.yaml does not exist, STOP. Say: "No time register at [billing_data_path]/time-register.yaml. That file is absent, not empty -- billing data may be unsynced, the data path may be wrong, or the file may have been moved. I am not going to report figures I cannot read." Do not create it, do not proceed with zeroes, and do not answer from earlier in the conversation. Absent is a different condition from empty or comment-only, which is the normal state of a fresh install.

Read [billing_data_path]/time-register.yaml. Filter to:

  • client: [client-slug]
  • status: approved
  • Within the period if --period was specified

If no entries match: "No approved entries found for [client] in this period. Run /billing-legal:wip-review first to approve pending entries."

Read [billing_data_path]/clients/[slug].yaml for:

  • name (display name)
  • billing_contact
  • billing_address
  • arrangement
  • budget_cap, budget_billed, retainer_balance

4. Determine invoice number

Read [billing_data_path]/invoice-register.yaml. Find the highest existing invoice number for the current year. Assign the next sequential number: [prefix]-[YYYY]-[NNN] (zero-padded 3 digits, e.g., INV-2026-007).

5. Confirm before generating

Show a pre-invoice summary:

Ready to generate Invoice [number]

Client:     [Client Name]
Period:     [date range or "All approved entries"]
Entries:    [N] entries
Total hours: [Nh]
Total fees:  $[total]
Arrangement: [arrangement]

Retainer balance (before this invoice): $[balance]
Retainer balance (after this invoice):  $[balance - fees]

Continue? [Y/n]  (or 'wip' to go back to WIP review)

If retainer balance would go negative, warn:

⚠ This invoice exceeds the retainer balance by $[overage]. Client will owe the balance on net payment terms.

6. Generate the invoice exhibit

Write the invoice to [billing_data_path]/invoices/[invoice-number].md:

---
invoice: [invoice-number]
client: [client-slug]
date: [YYYY-MM-DD]
period_start: [YYYY-MM-DD]
period_end: [YYYY-MM-DD]
total_hours: [Nh]
total_fees: [amount]
status: issued
---

# Time & Billing Detail
## Supporting Documentation — Invoice [invoice-number]

**[Firm Name]**
[Billing Address]
[Billing Email]

---

**Client:** [Client Display Name]
**Attention:** [billing_contact name]
**Billing Address:** [billing_address]

**Invoice:** [invoice-number]
**Invoice Date:** [YYYY-MM-DD]
**Billing Period:** [period start] – [period end]

---

## Time Entries

[Group by matter slug. For each matter group:]

### [Matter slug] — [Client name] ([matter description if available])

| Date | Attorney | Description | Code | Hours | Rate | Amount |
|---|---|---|---|---|---|---|
| [date] | [name] | [narrative] | [code or —] | [hours]h | $[rate]/hr | $[amount] |

**Matter subtotal: [Nh]  ·  $[amount]**

---

[Next matter group...]

---

## Summary

| | Hours | Amount |
|---|---|---|
| **Total billable time** | **[Nh]** | **$[total]** |
[If there were write-downs, emit one row per written-down entry and name whose time it was.
Compute each from that entry's `original_hours - hours` and `original_amount - amount`:]
| Write-down - [Attorney Name], [date] | [Nh] | ($[amount]) |

A single aggregated "write-downs" row is ambiguous on any invoice with more than one timekeeper.
The hours figure can also collide with a billed entry's hours -- an invoice showing 0.2h billed
and 0.2h written down reads as one line item, not two. Name the attorney and the date so the
client can see whose time was absorbed and against what.

[If retainer:]
| Retainer on file | | $[retainer_balance] |
| Less: this invoice | | ($[total]) |
| **Retainer balance after invoice** | | **$[balance]** |

---

*This document is supporting detail for Invoice [invoice-number]. Payment terms and remittance instructions are on the invoice. Questions: [billing_email].*

*Prepared [date] · [Firm Name]*

Omit the Code column entirely if Task codes: hidden is set in config.

For flat-fee matters:

  • Include the time entries table (client may want to see the work performed)
  • Replace the amount column with "— (flat fee)"
  • Summary section shows hours but no dollar total; instead: "Flat fee arrangement — see invoice for amount"

For contingency matters:

  • Include time entries with $0 rate
  • Note: "Contingency matter — fees contingent on outcome"

7. Add activity audit trail (if enabled)

Check config for Activity log on invoice: enabled. If enabled:

For each matter group in the invoice, collect all activity_log entries from the time register entries in that group (skip entries where activity_log is null). If any exist, append a collapsed audit section immediately after the matter's time entries table:

<details>
<summary>AI session activity — audit trail</summary>

| Time | Action | Document |
|---|---|---|
| [YYYY-MM-DD HH:MM] | [Edit/Write/Read] | [filename] |

</details>

Parse each activity log entry (format: ISO8601_TIMESTAMP|TOOL_NAME|FILENAME). Convert timestamp to YYYY-MM-DD HH:MM in local time. Sort by timestamp ascending. Deduplicate: if the same file appears more than once with the same action, collapse to one row and note the count, e.g., vendor-nda.docx (×3).

The <details> block keeps the audit trail accessible without cluttering the invoice exhibit. Most Markdown renderers (GitHub, VS Code, browser-based viewers) render it as a collapsed section.

If Activity log on invoice: disabled (or the setting is absent from config), skip this step entirely.

9. Update registers

Update invoice-register.yaml — append:

- id: [invoice-number]
  client: [client-slug]
  date: [YYYY-MM-DD]
  period_start: [YYYY-MM-DD]
  period_end: [YYYY-MM-DD]
  total_hours: [N]
  total_fees: [amount]
  entry_ids: [[list of te-* ids]]
  status: issued

Update time-register.yaml — for each included entry, change status: approved → status: billed and set invoice_id: [invoice-number].

Update client YAML — add invoice total to budget_billed. If retainer: subtract from retainer_balance.

Update CLAUDE.md — increment Next invoice number by 1.

10. Confirm and close

✓ Invoice [invoice-number] generated: File: [billing_data_path]/invoices/[invoice-number].md Entries marked billed: [N] Total: $[amount]

To print or share: open the file and copy/paste into Word, or convert to PDF with any Markdown-to-PDF tool.

To view: /billing-legal:billing-report --invoice [invoice-number]

LEDES export: if your client requires LEDES 1998B format for their e-billing system, run: /billing-legal:ledes-export --invoice [invoice-number]


What this skill does not do

  • Send invoices — attorney copies the Markdown to their invoicing system or email
  • Interface with accounting software — the Markdown is designed for copy/paste
  • Generate the primary invoice (letterhead, payment terms) — this document is supporting detail; the attorney creates the primary invoice in their billing system
  • Delete or undo issued invoices — contact billing counsel if a correction is needed after issuance

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.