Manage Accounting Skill

Integrates with Xero to provide complete financial intelligence - the foundation for autonomous business management and CEO briefings.

Core Responsibilities

Sync Xero Transactions: Fetch and sync bank/credit card transactions from Xero
Auto-Categorize Expenses: Intelligently categorize transactions (80%+ accuracy target)
Generate Invoices: Create professional invoices via Xero API
Bank Reconciliation: Match transactions with invoices and payments
Financial Reporting: Update Dashboard with revenue, expenses, cash flow
Cost Optimization: Identify duplicate subscriptions and unused services

When This Skill Activates

Trigger phrases:

"sync accounting"
"update xero"
"categorize expenses"
"create invoice"
"financial summary"
"reconcile transactions"
"check revenue"
"expense report"
"subscription audit"

Auto-activates when:

Scheduled daily sync (e.g., 6:00 AM)
New transactions detected in Xero
CEO briefing generation needs financial data
User requests financial status

Core Workflow

Phase 1: Xero Transaction Sync

When: Daily at 6:00 AM or on-demand

Connect to Xero via MCP Server
- Verify Xero MCP server running
- Check OAuth2 token valid (refresh if needed)
- Test connection to Xero API
Fetch New Transactions
- Get bank/credit card transactions from last sync
- Query invoices (sent and received)
- Retrieve payment records
- Pull contact/vendor information
Write to Vault
- Update Vault/Accounting/Current_Month.md with new transactions
- Create individual transaction files in Vault/Accounting/Transactions/
- Filename format: TRANS_YYYY-MM-DD_[Description].md
- Include metadata: date, amount, vendor, category (if already categorized in Xero)
Update Dashboard
- Add sync timestamp to Vault/Dashboard.md
- Include transaction count (new expenses, new revenue)
- Flag any sync errors

Helper Script:

python .claude/skills/manage-accounting/scripts/xero_sync.py [--date-range YYYY-MM-DD:YYYY-MM-DD]

See reference/reconciliation-guide.md for detailed sync procedures.

Phase 2: Expense Categorization

When: After sync or when uncategorized transactions detected

Identify Uncategorized Transactions
- Scan Vault/Accounting/Transactions/ for transactions missing category
- Check Vault/Accounting/Current_Month.md for uncategorized items
- Priority: Expenses first (revenue usually clear)
Auto-Categorize Using Rules
- Load expense-rules.md
- Apply pattern matching (vendor name, description, amount patterns)
- Check against xero-categories.md for valid categories
- Use tax-categories.md for tax treatment
Categorization Logic (80%+ Accuracy Target)
- Subscription Services: Match vendor name against known subscriptions
  - Adobe, Netflix, Spotify, GitHub, AWS, etc.
  - Category: "Software & Subscriptions" or "Marketing & Advertising"
- Recurring Payments: Identify by amount consistency + vendor
- Office Supplies: Match vendors like Staples, Amazon Business
- Professional Services: Contractors, consultants (look for invoice references)
- Travel & Meals: Airlines, hotels, restaurants (check tax deductibility)
Update Xero via MCP
- For high-confidence categorizations (>90%), update directly in Xero
- For medium-confidence (70-90%), create approval request
- For low-confidence (<70%), flag for manual review
Update Transaction Files
- Add category to transaction metadata
- Include confidence score
- Log categorization reasoning
Handle Uncertain Transactions
- Create review file in Vault/Accounting/Needs_Review/
- Include similar past transactions for reference
- Suggest 2-3 possible categories with reasoning

Helper Script:

python .claude/skills/manage-accounting/scripts/categorize_expense.py [--transaction-id ID] [--dry-run]

See expense-rules.md for complete categorization logic.

Phase 3: Invoice Generation

When: User requests invoice or client payment needed

Gather Invoice Details
- Check request for: client name, amount, description, date
- Look up client contact in Xero
- Reference Vault/Business_Goals.md for rates/pricing
- Use invoice-templates.md
Validate Information
- Confirm client exists in Xero contacts
- Verify amount matches agreed rate/scope
- Check for duplicate invoices (prevent re-billing)
- Ensure all required fields present
Create Approval Request
- ALWAYS require approval for invoices
- Use handle-approval skill to create approval request
- Include:
  - Client name and contact
  - Invoice amount (line items)
  - Due date
  - Payment terms
  - Preview of invoice (text format)
- Save approval request in Vault/Pending_Approval/
Execute After Approval
- Once moved to Vault/Approved/, generate invoice in Xero
- Use Xero MCP to create invoice
- Capture invoice number and URL
- Optionally send invoice via email (separate approval)
Update Records
- Save invoice copy to Vault/Accounting/Invoices/INV_[Number]_[Client].pdf
- Log to Vault/Accounting/Current_Month.md
- Update Dashboard with invoice sent
- Track invoice status (unpaid, paid, overdue)

Helper Script:

python .claude/skills/manage-accounting/scripts/generate_invoice.py --client "Client Name" --amount 1500 --description "Services rendered"

See invoice-templates.md for template options.

Phase 4: Bank Reconciliation

When: Weekly or before CEO briefing generation

Match Transactions
- Compare bank transactions with Xero invoices
- Identify payments received (match invoice amounts)
- Flag missing payments (overdue invoices)
- Detect unexpected transactions
Reconcile Expenses
- Match expense transactions with receipts/approvals
- Verify categorizations against bank statements
- Identify discrepancies
Generate Reconciliation Report
- Summary: Total reconciled vs unreconciled
- List unmatched transactions
- Overdue invoices report
- Discrepancies flagging for review
Update Dashboard
- Add reconciliation status to Vault/Dashboard.md
- Include outstanding items count
- Flag high-priority discrepancies

See reconciliation-guide.md for detailed procedures.

Phase 5: Financial Reporting & Cost Optimization

When: Daily dashboard update or CEO briefing generation

Calculate Financial Metrics
- Revenue:
  - This week revenue
  - Month-to-date (MTD)
  - vs target from Vault/Business_Goals.md
- Expenses:
  - Weekly expenses by category
  - MTD expenses
  - vs budget targets
- Cash Flow:
  - Revenue - Expenses
  - Trend (improving/declining)
- Outstanding:
  - Unpaid invoices total
  - Overdue invoices (>30 days)
Subscription Audit (Cost Optimization)
- Identify recurring subscriptions from expense patterns
- Check usage (cross-reference with other data sources if available)
- Flag potential savings:
  - No usage in 30+ days
  - Duplicate functionality with other tools
  - Cost increased >20% without notification
- Generate recommendation for cancellation or negotiation

Update Dashboard

Add financial summary section to Vault/Dashboard.md

Format:

## Financial Summary (Updated: YYYY-MM-DD HH:MM)
- **Revenue MTD**: $X,XXX (XX% of $X,XXX target)
- **Expenses MTD**: $X,XXX (XX% of $X,XXX budget)
- **Cash Flow**: +/- $X,XXX
- **Outstanding**: $X,XXX (X invoices)
- **Alert**: [Any overdue invoices or unusual expenses]

Proactive Recommendations
- If cost optimization opportunity detected, add to Dashboard
- Example: "Notion: No activity 45 days. Cost: $15/mo → Annual savings: $180"
- Create note in Vault/Accounting/Recommendations/

Security Safeguards

Before Syncing:

✅ Xero MCP server authenticated
✅ OAuth2 token valid
✅ Network connection stable
✅ Vault backup exists

Before Categorizing:

✅ Transaction not already categorized
✅ Category exists in Xero chart of accounts
✅ Confidence threshold met (or approval requested)
✅ Tax treatment correct

Before Creating Invoice:

✅ ALWAYS require approval (no auto-invoicing)
✅ Client exists in Xero
✅ Amount validated against rate sheet
✅ No duplicate invoice exists
✅ All required fields populated

Never Auto-Execute:

❌ Invoice generation (always requires approval)
❌ Invoice sending (requires separate approval)
❌ Payment processing
❌ Subscription cancellations (recommend only)
❌ Deleting transactions

Reference Files

Progressive disclosure - load on demand:

xero-categories.md
- Standard Xero chart of accounts
- Category hierarchy
- When to use each category
- Tax implications per category
expense-rules.md
- Auto-categorization rules (vendor patterns)
- Confidence scoring logic
- Special cases and exceptions
- Rule priority order
invoice-templates.md
- Standard invoice templates
- Template selection logic
- Required fields per template
- Customization options
reconciliation-guide.md
- Step-by-step reconciliation process
- Matching algorithms
- Discrepancy handling
- Reporting format
tax-categories.md
- Tax treatment by expense type
- Deductible vs non-deductible
- GST/VAT handling
- Documentation requirements

Helper Scripts

xero_sync.py

Purpose: Fetch transactions from Xero and update Vault

Usage:

# Sync today's transactions
python .claude/skills/manage-accounting/scripts/xero_sync.py

# Sync specific date range
python .claude/skills/manage-accounting/scripts/xero_sync.py --date-range 2026-01-01:2026-01-11

# Dry run (preview without writing)
python .claude/skills/manage-accounting/scripts/xero_sync.py --dry-run

# JSON output
python .claude/skills/manage-accounting/scripts/xero_sync.py --json

categorize_expense.py

Purpose: Auto-categorize transactions using pattern matching

Usage:

# Categorize all uncategorized transactions
python .claude/skills/manage-accounting/scripts/categorize_expense.py

# Categorize specific transaction
python .claude/skills/manage-accounting/scripts/categorize_expense.py --transaction-id TX123

# Dry run (preview categorizations)
python .claude/skills/manage-accounting/scripts/categorize_expense.py --dry-run

# Lower confidence threshold (more aggressive)
python .claude/skills/manage-accounting/scripts/categorize_expense.py --threshold 0.7

generate_invoice.py

Purpose: Generate invoice draft for approval

Usage:

# Create invoice approval request
python .claude/skills/manage-accounting/scripts/generate_invoice.py \
  --client "Client A" \
  --amount 1500 \
  --description "Consulting services - January 2026"

# Use specific template
python .claude/skills/manage-accounting/scripts/generate_invoice.py \
  --client "Client B" \
  --amount 2500 \
  --template "project-based"

# Include line items from file
python .claude/skills/manage-accounting/scripts/generate_invoice.py \
  --client "Client C" \
  --line-items-file Vault/Projects/ClientC/invoice_items.json

Integration with Other Skills

Skills that use manage-accounting:

generate-ceo-briefing → Reads financial data for weekly business audit
handle-approval → Executes approved invoices
monitor-system → Checks Xero sync health

Provides data to:

Vault/Dashboard.md → Financial summary section
Vault/Briefings/ → Revenue/expense data for CEO reports
Vault/Accounting/ → Complete financial records

Workflow:

1. Daily 6:00 AM: xero_sync.py runs automatically
2. New transactions → categorize_expense.py auto-categorizes
3. High-confidence → Update Xero directly
4. Low-confidence → Create review file
5. User requests invoice → generate_invoice.py creates approval
6. Approval granted → Create invoice in Xero
7. Weekly: Reconciliation + cost optimization analysis
8. Sunday: Financial data fed to generate-ceo-briefing

Dashboard Logging

All accounting activity logged to Vault/Dashboard.md:

### [Timestamp] - Accounting Activity

**Xero Sync:**
- Synced: X transactions (X expenses, X revenue)
- Date range: YYYY-MM-DD to YYYY-MM-DD
- Status: Success/Errors

**Expense Categorization:**
- Categorized: X transactions
- Confidence: High (X), Medium (X), Low (X)
- Pending review: X transactions

**Invoice Created:**
- Client: [Client Name]
- Amount: $X,XXX
- Status: Pending Approval
- File: Vault/Pending_Approval/APPROVAL_INVOICE_[...]

**Financial Summary:**
- Revenue MTD: $X,XXX (XX% of target)
- Expenses MTD: $X,XXX
- Cash Flow: +/- $X,XXX
- Outstanding: $X,XXX

**Cost Optimization:**
- Recommendation: [Subscription/service to cancel]
- Potential Savings: $X/month ($X/year)

Success Criteria

This skill works correctly when:

✅ Daily Xero sync runs automatically (99%+ success rate) ✅ Transactions correctly synced to Vault ✅ 80%+ auto-categorization accuracy ✅ All invoices require and receive approval ✅ Invoices successfully created in Xero after approval ✅ Financial dashboard updated daily with accurate metrics ✅ Cost optimization recommendations relevant and actionable ✅ Reconciliation reports generated weekly ✅ Zero unauthorized financial actions ✅ Complete audit trail maintained

Common Issues

Xero MCP Connection Failed:

Check MCP server running: ps aux | grep xero-mcp
Verify OAuth2 token not expired
Test connection: python scripts/xero_sync.py --test-connection
Re-authenticate if needed

Categorization Low Accuracy (<80%):

Review and update expense-rules.md
Add vendor-specific patterns
Check Xero categories match xero-categories.md
Adjust confidence threshold if too conservative

Invoice Generation Failed:

Verify client exists in Xero contacts
Check all required fields present
Ensure no duplicate invoice number
Review Xero API error logs

Sync Not Running Daily:

Check cron job / Task Scheduler configuration
Verify orchestrator.py scheduling working
Check system logs for errors
Ensure Xero API rate limits not exceeded

Reconciliation Discrepancies:

Verify transaction dates match bank statement
Check for manual entries in Xero
Review transaction matching rules
Ensure all transactions synced

External Dependencies

Required:

Xero account with API access
Xero MCP Server installed and configured
OAuth2 credentials configured in Claude Code
handle-approval skill operational

Optional:

Bank account API for enhanced reconciliation
Receipt scanning for expense verification

Setup Checklist

Before first use:

Skill Version: 1.0 Last Updated: 2026-01-11 Branch: feat/gold-accounting-xero Dependencies: handle-approval, Xero MCP Server