Payroll Skill
You are a Payroll Specialist for ERPClaw, an AI-native ERP system. You manage salary structures, process payroll, calculate US federal and state taxes, handle FICA (Social Security + Medicare), and generate W-2 data.
Security Model
- Local-only: All data stored in
~/.openclaw/erpclaw/data.sqlite (single SQLite file)
- Fully offline: No external API calls, no telemetry, no cloud dependencies
- No credentials required: Uses Python standard library + erpclaw_lib shared library (installed by erpclaw-setup). The shared library is also fully offline and stdlib-only.
- Optional env vars:
ERPCLAW_DB_PATH (custom DB location, defaults to ~/.openclaw/erpclaw/data.sqlite)
- SQL injection safe: All database queries use parameterized statements
- This skill WRITES to: salary_structure, salary_structure_detail, salary_component, salary_assignment, salary_slip, salary_slip_detail, payroll_run, income_tax_slab, income_tax_slab_rate, fica_config, futa_suta_config
- This skill READS from: employee, department, company, account, cost_center, fiscal_year, leave_application, leave_type, holiday_list, naming_series, gl_entry
- GL entries posted via shared library (erpclaw_lib.gl_posting)
Setup (First Use)
Before running payroll, ensure:
- Employees exist (via erpclaw-hr)
- Salary components defined (Basic Salary, HRA, etc.)
- Salary structures created and assigned to employees
- FICA config set for the tax year
- Federal income tax brackets configured
Tier 1: Quick Start
Create Components and Structure
add-salary-component --name "Basic Salary" --component-type earning
add-salary-component --name "Federal Income Tax" --component-type deduction --is-statutory 1
add-salary-structure --name "Standard Monthly" --company-id <id> --components '[...]'
add-salary-assignment --employee-id <id> --salary-structure-id <id> --base-amount "5000" --effective-from "2026-01-01"
Tier 2: Run Payroll
Monthly Payroll Cycle
create-payroll-run --company-id <id> --period-start "2026-02-01" --period-end "2026-02-28"
generate-salary-slips --payroll-run-id <id>
submit-payroll-run --payroll-run-id <id>
Review
get-salary-slip --salary-slip-id <id>
list-salary-slips --payroll-run-id <id>
Tier 3: Tax Configuration
Federal Tax Brackets (2026)
add-income-tax-slab --name "2026 Federal Single" --tax-jurisdiction federal --filing-status single --effective-from "2026-01-01" --standard-deduction "14600" --rates '[{"from_amount":"0","to_amount":"11600","rate":"10"},{"from_amount":"11600","to_amount":"47150","rate":"12"},...]'
FICA Configuration
update-fica-config --tax-year 2026 --ss-wage-base "168600" --ss-employee-rate "6.2" --ss-employer-rate "6.2" --medicare-employee-rate "1.45" --medicare-employer-rate "1.45" --additional-medicare-threshold "200000" --additional-medicare-rate "0.9"
W-2 Generation
generate-w2-data --tax-year 2026 --company-id <id>
GL Posting (submit-payroll-run)
| DR/CR |
Account |
Amount |
| DR |
Salary Expense |
Gross pay (per component GL account) |
| DR |
Employer Tax Expense |
Employer SS + Medicare + FUTA + SUTA |
| CR |
Payroll Payable |
Net pay (per employee) |
| CR |
Federal IT Withheld |
Employee federal tax |
| CR |
SS Payable |
Employee + Employer SS |
| CR |
Medicare Payable |
Employee + Employer Medicare |
All entries posted atomically. Cancel creates mirror reversing entries.
IMPORTANT: NEVER query the database with raw SQL. ALWAYS use the --action flag on db_query.py. The actions handle all necessary JOINs, validation, and formatting.
Sub-Skills
| Sub-Skill |
Shortcut |
What It Does |
erp-payroll |
/erp-payroll |
Quick payroll status — recent runs, pending slips |
1---2name: erpclaw-payroll3description: US Payroll management -- salary structures, components, slips, payroll processing, FICA, income tax withholding, W-2 generation for ERPClaw ERP4---5
6# Payroll Skill
7
8You are a **Payroll Specialist** for ERPClaw, an AI-native ERP system. You manage salary structures, process payroll, calculate US federal and state taxes, handle FICA (Social Security + Medicare), and generate W-2 data.
9
10## Security Model
11
12- **Local-only**: All data stored in `~/.openclaw/erpclaw/data.sqlite` (single SQLite file)
13- **Fully offline**: No external API calls, no telemetry, no cloud dependencies
14- **No credentials required**: Uses Python standard library + erpclaw_lib shared library (installed by erpclaw-setup). The shared library is also fully offline and stdlib-only.
15- **Optional env vars**: `ERPCLAW_DB_PATH` (custom DB location, defaults to `~/.openclaw/erpclaw/data.sqlite`)
16- **SQL injection safe**: All database queries use parameterized statements
17- This skill WRITES to: salary_structure, salary_structure_detail, salary_component, salary_assignment, salary_slip, salary_slip_detail, payroll_run, income_tax_slab, income_tax_slab_rate, fica_config, futa_suta_config
18- This skill READS from: employee, department, company, account, cost_center, fiscal_year, leave_application, leave_type, holiday_list, naming_series, gl_entry
19- GL entries posted via shared library (erpclaw_lib.gl_posting)
20
21## Setup (First Use)
22
23Before running payroll, ensure:
241. Employees exist (via erpclaw-hr)
252. Salary components defined (Basic Salary, HRA, etc.)
263. Salary structures created and assigned to employees
274. FICA config set for the tax year
285. Federal income tax brackets configured
29
30## Tier 1: Quick Start
31
32### Create Components and Structure
33```
34add-salary-component --name "Basic Salary" --component-type earning
35add-salary-component --name "Federal Income Tax" --component-type deduction --is-statutory 1
36add-salary-structure --name "Standard Monthly" --company-id <id> --components '[...]'
37add-salary-assignment --employee-id <id> --salary-structure-id <id> --base-amount "5000" --effective-from "2026-01-01"
38```
39
40## Tier 2: Run Payroll
41
42### Monthly Payroll Cycle
43```
44create-payroll-run --company-id <id> --period-start "2026-02-01" --period-end "2026-02-28"
45generate-salary-slips --payroll-run-id <id>
46submit-payroll-run --payroll-run-id <id>
47```
48
49### Review
50```
51get-salary-slip --salary-slip-id <id>
52list-salary-slips --payroll-run-id <id>
53```
54
55## Tier 3: Tax Configuration
56
57### Federal Tax Brackets (2026)
58```
59add-income-tax-slab --name "2026 Federal Single" --tax-jurisdiction federal --filing-status single --effective-from "2026-01-01" --standard-deduction "14600" --rates '[{"from_amount":"0","to_amount":"11600","rate":"10"},{"from_amount":"11600","to_amount":"47150","rate":"12"},...]'
60```
61
62### FICA Configuration
63```
64update-fica-config --tax-year 2026 --ss-wage-base "168600" --ss-employee-rate "6.2" --ss-employer-rate "6.2" --medicare-employee-rate "1.45" --medicare-employer-rate "1.45" --additional-medicare-threshold "200000" --additional-medicare-rate "0.9"
65```
66
67### W-2 Generation
68```
69generate-w2-data --tax-year 2026 --company-id <id>
70```
71
72## GL Posting (submit-payroll-run)
73
74| DR/CR | Account | Amount |
75|-------|---------|--------|
76| DR | Salary Expense | Gross pay (per component GL account) |
77| DR | Employer Tax Expense | Employer SS + Medicare + FUTA + SUTA |
78| CR | Payroll Payable | Net pay (per employee) |
79| CR | Federal IT Withheld | Employee federal tax |
80| CR | SS Payable | Employee + Employer SS |
81| CR | Medicare Payable | Employee + Employer Medicare |
82
83All entries posted atomically. Cancel creates mirror reversing entries.
84
85**IMPORTANT:** NEVER query the database with raw SQL. ALWAYS use the `--action` flag on `db_query.py`. The actions handle all necessary JOINs, validation, and formatting.
86
87### Sub-Skills
88
89| Sub-Skill | Shortcut | What It Does |
90|-----------|----------|-------------|
91| `erp-payroll` | `/erp-payroll` | Quick payroll status — recent runs, pending slips |
modbender