{ "schemaVersion": "1.0", "item": { "slug": "nicholasrae-expense-tracker", "name": "Expense Tracker", "source": "tencent", "type": "skill", "category": "效率提升", "sourceUrl": "https://clawhub.ai/nicholasrae/nicholasrae-expense-tracker", "canonicalUrl": "https://clawhub.ai/nicholasrae/nicholasrae-expense-tracker", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/nicholasrae-expense-tracker", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=nicholasrae-expense-tracker", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "README.md", "SKILL.md", "references/budgets.json", "references/categories.json", "scripts/add-expense.sh", "scripts/budget-check.sh" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-23T16:43:11.935Z", "expiresAt": "2026-04-30T16:43:11.935Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/nicholasrae-expense-tracker" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/nicholasrae-expense-tracker", "agentPageUrl": "https://openagent3.xyz/skills/nicholasrae-expense-tracker/agent", "manifestUrl": "https://openagent3.xyz/skills/nicholasrae-expense-tracker/agent.json", "briefUrl": "https://openagent3.xyz/skills/nicholasrae-expense-tracker/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Expense Tracker Skill", "body": "Track, categorize, and budget personal expenses through natural conversation. Users text expenses in plain language and the AI logs them, tracks budgets, and generates reports." }, { "title": "Skill Directory", "body": "skills/expense-tracker/\n├── SKILL.md # This file — AI instructions\n├── references/\n│ ├── categories.json # Category definitions + keyword matching\n│ └── budgets.json # Monthly budget limits (user-editable)\n├── scripts/\n│ ├── add-expense.sh # Add expense to ledger\n│ ├── query.sh # Query/filter expenses\n│ └── budget-check.sh # Check spending vs budget\n├── templates/\n│ ├── weekly-report.md # Weekly report template\n│ └── monthly-report.md # Monthly report template\n└── expenses/\n └── ledger.json # Transaction data (auto-created)" }, { "title": "1. Parsing Natural Language Expenses", "body": "When a user mentions spending money, extract these fields:\n\nFieldRequiredHow to ExtractamountYesDollar amounts: \"$45\", \"45 dollars\", \"forty-five bucks\", \"45.99\"vendorYesNamed entity after \"at\", \"from\", \"to\", or contextual merchant namecategoryAutoMatch vendor/context against references/categories.json keywordsdateDefault today\"today\", \"yesterday\", \"last Tuesday\", \"on 2/14\", explicit datesnotesOptionalAnything extra the user adds — \"for the party\", \"work expense\"" }, { "title": "Parsing Examples", "body": "User Saysamountvendorcategorydatenotes\"spent $45 at Costco\"45CostcoGroceriestoday\"grabbed lunch for $18 at Chipotle yesterday\"18ChipotleDiningyesterday\"$120 electric bill\"120Electric companyUtilitiestoday\"filled up the tank, 55 bucks at Shell\"55ShellGas/Transporttoday\"Netflix $15.99\"15.99NetflixSubscriptionstoday\"dropped $200 at Target for birthday stuff\"200TargetShoppingtodaybirthday stuff\"refund from Amazon $35\"-35AmazonShoppingtodayrefund\"paid rent $2000\"2000Rent/LandlordHousingtoday\"spent $5.50 at starbucks yesterday\"5.50StarbucksDiningyesterday\"vet visit for the dog, $280\"280VetPetstoday\"car insurance $180\"180Car insuranceInsurancetoday\"groceries and some clothes at Target $150\"150TargetShoppingtodaygroceries and clothes (ask user to split or pick)\"got reimbursed $45 for work lunch\"-45WorkDiningtodayreimbursement" }, { "title": "Ambiguous Categories", "body": "When a vendor could match multiple categories (e.g., \"Walmart\" could be Groceries or Shopping):\n\nBest-guess first: Pick the most likely category based on context\nConfirm with user: \"I logged $85 at Walmart as Groceries — is that right, or was this more of a Shopping trip?\"\nRemember preferences: If the user corrects, note the preference for future entries\n\nWhen no category matches at all, use Miscellaneous and tell the user: \"Logged under Miscellaneous — want me to put this in a specific category?\"" }, { "title": "/add — Log an Expense", "body": "Log an expense explicitly.\n\nUsage: /add [category] [date] [notes]\n\nImplementation: Run the add-expense script:\n\nbash skills/expense-tracker/scripts/add-expense.sh \"\" \"\" \"\" \"\"\n\nExamples:\n\n/add 45 Costco → logs $45 at Costco, auto-categorized, today's date\n/add 18.50 Chipotle Dining yesterday → $18.50 dining, yesterday\n/add -35 Amazon Shopping 2026-02-10 \"refund for headphones\" → refund\n\nMost of the time, users won't use /add — they'll just say \"spent $45 at Costco\" and you parse it." }, { "title": "/spending — View Spending", "body": "Query expenses with optional filters.\n\nUsage: /spending [period] [category]\n\nImplementation: Run the query script:\n\nbash skills/expense-tracker/scripts/query.sh [--from DATE] [--to DATE] [--category CAT] [--format summary|detail|json]\n\nExamples:\n\n/spending → current month summary\n/spending this week → this week's expenses\n/spending Dining → all dining expenses this month\n/spending February detail → detailed February breakdown\n\"how much have I spent on groceries?\" → query with --category Groceries\n\"what did I spend last week?\" → query with appropriate date range\n\nFormat options:\n\nsummary (default) — totals by category\ndetail — itemized list with all fields\njson — raw JSON output" }, { "title": "/budget — Budget Status", "body": "Check spending against budget limits.\n\nUsage: /budget [month]\n\nImplementation: Run the budget check script:\n\nbash skills/expense-tracker/scripts/budget-check.sh [YYYY-MM]\n\nExamples:\n\n/budget → current month budget status\n/budget 2026-01 → January budget review\n\"how's my budget looking?\" → run budget check\n\nAlso supports adjusting budgets:\n\n\"set my dining budget to $400\" → update references/budgets.json using jq --arg (never interpolate user values into jq code directly)\n\"what's my grocery budget?\" → read from budgets.json" }, { "title": "/categories — View/Manage Categories", "body": "Show available categories or recategorize expenses.\n\nExamples:\n\n/categories → list all categories\n/categories Dining → show Dining keywords and recent expenses\n\"move expense #12 to Entertainment\" → update ledger entry's category" }, { "title": "3. Category Auto-Matching", "body": "Use references/categories.json to match vendors to categories. The matching algorithm:\n\nExact keyword match: Check if vendor name (lowercased) contains any keyword\nPartial match: Check if any keyword is a substring of the vendor name\nContext clues: Use surrounding words — \"lunch at\" → Dining, \"filled up at\" → Gas/Transport\nFallback: Miscellaneous" }, { "title": "Available Categories", "body": "Groceries, Dining, Gas/Transport, Subscriptions, Health/Fitness, Entertainment, Shopping, Utilities, Housing, Personal Care, Education, Gifts, Travel, Insurance, Pets, Miscellaneous." }, { "title": "Priority Order (when multiple match)", "body": "Most specific keyword wins (\"Costco gas\" → Gas/Transport over Groceries)\nContext from user's message\nUser's historical pattern for that vendor\nAsk the user" }, { "title": "4. Budget Tracking", "body": "Budget configuration lives in references/budgets.json. The user edits this to set their limits." }, { "title": "Alert Thresholds", "body": "ThresholdEmojiAction< 50%⚪No alert50–79%🟢Informational only80–99%🟡Proactive warning: \"Heads up — Dining is at 85% of your $300 budget\"≥ 100%🔴Alert: \"You've exceeded your Dining budget ($312 / $300)\"" }, { "title": "When to Alert", "body": "On every expense: After logging, silently check the category budget. Only speak up at 80%+ threshold.\nOn /budget command: Show full breakdown with all categories.\nWeekly: If generating a weekly report, include budget status section." }, { "title": "Proactive Budget Warnings", "body": "After logging an expense that pushes a category past 80%, add a note:\n\n✅ Expense #24: $45.00 at Olive Garden (Dining) on 2026-02-17\n⚠️ Heads up — Dining is now at $275 / $300 (92%) for February.\n\nAfter exceeding 100%:\n\n✅ Expense #25: $38.00 at Thai Palace (Dining) on 2026-02-19\n🔴 Dining has exceeded your February budget: $313 / $300 (104%)" }, { "title": "Weekly Report", "body": "Use templates/weekly-report.md as a guide. Generate when the user asks \"weekly report\", \"how'd I do this week\", etc.\n\nTo generate, run query.sh for the week's date range, then format the results using the template structure:\n\n# Get this week's data\nbash skills/expense-tracker/scripts/query.sh --from 2026-02-10 --to 2026-02-16 --format json\n\n# Get last week for comparison\nbash skills/expense-tracker/scripts/query.sh --from 2026-02-03 --to 2026-02-09 --format json\n\n# Get budget status\nbash skills/expense-tracker/scripts/budget-check.sh\n\nInclude: category breakdown, top expenses, budget status, week-over-week trend." }, { "title": "Monthly Report", "body": "Use templates/monthly-report.md as a guide. Generate for \"monthly report\", \"how'd February go\", end-of-month reviews.\n\n# Current month data\nbash skills/expense-tracker/scripts/query.sh --from 2026-02-01 --to 2026-02-28 --format json\n\n# Previous month for comparison\nbash skills/expense-tracker/scripts/query.sh --from 2026-01-01 --to 2026-01-31 --format json\n\n# Budget check\nbash skills/expense-tracker/scripts/budget-check.sh 2026-02\n\nInclude: full category breakdown, top expenses, weekly breakdown, month-over-month comparison, savings rate (if income is set in budgets.json)." }, { "title": "Refunds", "body": "Detect words: \"refund\", \"returned\", \"got back\", \"credit\", \"reimbursement\"\nStore as negative amount: add-expense.sh -35 \"Shopping\" \"Amazon\" \"2026-02-15\" \"refund\"\nRefunds reduce the category total in budget calculations" }, { "title": "Splitting Expenses", "body": "\"Split $80 dinner with Sarah\" → log $40 (user's half)\n\"Split 3 ways: $120 at the bar\" → log $40\nConfirm the split: \"Logging your share: $40 at the bar (Dining). That right?\"" }, { "title": "Recurring Expenses", "body": "This skill doesn't auto-schedule recurring expenses\nWhen the user says \"Netflix again\" or \"monthly gym payment\", treat as a new entry\nThe AI can note: \"Want me to remind you about this next month?\" (but don't auto-create)" }, { "title": "Multi-Item Purchases", "body": "\"Spent $150 at Target on groceries and clothes\" → Ask user whether to log as one entry or split\nIf split: create separate entries per category\nIf single: pick the dominant category or ask which one\n\"Bought lunch and a coffee at Panera, $22\" → single Dining entry is fine (same category)" }, { "title": "Multi-Currency (Optional)", "body": "If the user mentions foreign currency: \"spent €50 in Paris\"\nLog the original amount and note the currency: add-expense.sh 55 \"Travel\" \"Paris restaurant\" \"2026-02-15\" \"€50 EUR\"\nConvert to USD for budget purposes (ask user for rate or use approximate)\nDefault behavior: assume USD unless told otherwise" }, { "title": "Corrections", "body": "\"Actually that Costco trip was $52, not $45\" → Find the recent Costco entry, update amount\n\"Delete expense #12\" → Remove from ledger using jq --argjson id 12 'map(select(.id != $id))' — always use --arg/--argjson, never interpolate IDs into filter strings\n\"Move #12 to Dining\" → Update category field" }, { "title": "Zero-Expense Days", "body": "Don't alert on no-spend days unless asked\nIn reports, show $0 days as positive (savings!)" }, { "title": "7. Conversational Patterns", "body": "The AI should handle these naturally without requiring commands:\n\nUser SaysAI Action\"spent $45 at Costco\"Parse → add expense → confirm → check budget\"how much have I spent this month?\"Run query.sh for current month → format summary\"am I over budget?\"Run budget-check.sh → report status\"weekly report\"Generate weekly report from template\"what did I spend on food?\"Query Groceries + Dining categories\"I got a $20 refund from Amazon\"Log negative amount → confirm\"split a $90 dinner with Jake\"Calculate half → log $45 → confirm\"that last one should be Entertainment, not Shopping\"Update most recent entry's category\"set grocery budget to $700\"Update budgets.json\"how much is left in my dining budget?\"Calculate: limit - spent this month\"show me everything from last week\"Query with date range, detail format\"what's my biggest expense this month?\"Query + sort by amount\"cancel that last expense\"Delete most recent ledger entry\"spent $5.50 at starbucks yesterday\"Parse date as yesterday → add expense\"vet bill was $280\"Log as Pets category\"car insurance came out, $180\"Log as Insurance category\"I spent like 50 bucks at Target\"Log $50, confirm amount approximation\"got reimbursed $45 from work\"Log as negative (reimbursement)\"how much did I spend on food this month?\"Query Groceries + Dining combined\"compare this month to last month\"Generate month-over-month comparison" }, { "title": "8. Example Full Interaction", "body": "User: spent $45 at Costco\nAI: ✅ Expense #1: $45.00 at Costco (Groceries) on 2026-02-17\n\nUser: grabbed lunch at Chipotle for $12.50\nAI: ✅ Expense #2: $12.50 at Chipotle (Dining) on 2026-02-17\n\nUser: $150 at Target yesterday\nAI: I logged $150 at Target as **Shopping** — was this groceries or more of a general shopping trip?\nUser: shopping\nAI: ✅ Expense #3: $150.00 at Target (Shopping) on 2026-02-16\n\nUser: how's my budget looking?\nAI:\n=== Budget Check: 2026-02 ===\n 🟢 OK Groceries $345 / $600 (58%)\n 🟡 WARN Dining $248 / $300 (83%)\n 🟢 OK Shopping $280 / $300 (93%)\n ⚪ LOW Gas/Transport $85 / $250 (34%)\n ...\n TOTAL: $1,245.00 / $4,950 (25%)\n\n⚠️ Heads up — Dining is at 83% and Shopping is at 93% of your February budget.\n\nUser: I got a refund from Amazon for $35\nAI: ✅ Refund #4: $35.00 from Amazon (Shopping) on 2026-02-17\n Shopping is now at $245 / $300 (82%) for February.\n\nUser: weekly report\nAI: [generates formatted weekly report from template]\n\nUser: set my dining budget to $400\nAI: Updated Dining budget: $300 → $400 for this month. You're now at $248 / $400 (62%) — much more breathing room! 🟢" }, { "title": "Ledger Entry (expenses/ledger.json)", "body": "[\n {\n \"id\": 1,\n \"amount\": 45.00,\n \"category\": \"Groceries\",\n \"vendor\": \"Costco\",\n \"date\": \"2026-02-17\",\n \"notes\": \"\",\n \"created_at\": \"2026-02-17T23:32:00Z\"\n },\n {\n \"id\": 2,\n \"amount\": -35.00,\n \"category\": \"Shopping\",\n \"vendor\": \"Amazon\",\n \"date\": \"2026-02-17\",\n \"notes\": \"refund for headphones\",\n \"created_at\": \"2026-02-17T23:45:00Z\"\n }\n]" }, { "title": "Key Rules", "body": "IDs: Incrementing integers, never reused\nAmounts: Always numbers. Positive = expense, negative = refund\nDates: ISO 8601 YYYY-MM-DD\nCategories: Must match a name in references/categories.json\ncreated_at: UTC timestamp of when the entry was created" }, { "title": "10. Script Reference", "body": "All scripts are in skills/expense-tracker/scripts/ and must be run with bash:\n\n# Add an expense\nbash skills/expense-tracker/scripts/add-expense.sh 45 \"Groceries\" \"Costco\" \"2026-02-17\" \"weekly groceries\"\n\n# Query expenses\nbash skills/expense-tracker/scripts/query.sh --from 2026-02-01 --to 2026-02-28 --category Dining --format summary\n\n# Check budget\nbash skills/expense-tracker/scripts/budget-check.sh 2026-02" }, { "title": "Script Arguments", "body": "add-expense.sh [date] [notes]\n\namount — number (negative for refunds)\ncategory — category name from categories.json\nvendor — merchant name\ndate — YYYY-MM-DD (default: today)\nnotes — optional description\n\nquery.sh [--from DATE] [--to DATE] [--category CAT] [--vendor TEXT] [--format FMT]\n\n--from — start date (inclusive)\n--to — end date (inclusive)\n--category — filter by category name\n--vendor — filter by vendor (partial match, case-insensitive)\n--format — summary (default), detail, or json\n\nbudget-check.sh [YYYY-MM]\n\nOptional month argument (default: current month)\nExit code 0 = all OK, exit code 1 = at least one category ≥ 80%" } ], "body": "Expense Tracker Skill\n\nTrack, categorize, and budget personal expenses through natural conversation. Users text expenses in plain language and the AI logs them, tracks budgets, and generates reports.\n\nSkill Directory\nskills/expense-tracker/\n├── SKILL.md # This file — AI instructions\n├── references/\n│ ├── categories.json # Category definitions + keyword matching\n│ └── budgets.json # Monthly budget limits (user-editable)\n├── scripts/\n│ ├── add-expense.sh # Add expense to ledger\n│ ├── query.sh # Query/filter expenses\n│ └── budget-check.sh # Check spending vs budget\n├── templates/\n│ ├── weekly-report.md # Weekly report template\n│ └── monthly-report.md # Monthly report template\n└── expenses/\n └── ledger.json # Transaction data (auto-created)\n\n1. Parsing Natural Language Expenses\n\nWhen a user mentions spending money, extract these fields:\n\nField\tRequired\tHow to Extract\namount\tYes\tDollar amounts: \"$45\", \"45 dollars\", \"forty-five bucks\", \"45.99\"\nvendor\tYes\tNamed entity after \"at\", \"from\", \"to\", or contextual merchant name\ncategory\tAuto\tMatch vendor/context against references/categories.json keywords\ndate\tDefault today\t\"today\", \"yesterday\", \"last Tuesday\", \"on 2/14\", explicit dates\nnotes\tOptional\tAnything extra the user adds — \"for the party\", \"work expense\"\nParsing Examples\nUser Says\tamount\tvendor\tcategory\tdate\tnotes\n\"spent $45 at Costco\"\t45\tCostco\tGroceries\ttoday\t\n\"grabbed lunch for $18 at Chipotle yesterday\"\t18\tChipotle\tDining\tyesterday\t\n\"$120 electric bill\"\t120\tElectric company\tUtilities\ttoday\t\n\"filled up the tank, 55 bucks at Shell\"\t55\tShell\tGas/Transport\ttoday\t\n\"Netflix $15.99\"\t15.99\tNetflix\tSubscriptions\ttoday\t\n\"dropped $200 at Target for birthday stuff\"\t200\tTarget\tShopping\ttoday\tbirthday stuff\n\"refund from Amazon $35\"\t-35\tAmazon\tShopping\ttoday\trefund\n\"paid rent $2000\"\t2000\tRent/Landlord\tHousing\ttoday\t\n\"spent $5.50 at starbucks yesterday\"\t5.50\tStarbucks\tDining\tyesterday\t\n\"vet visit for the dog, $280\"\t280\tVet\tPets\ttoday\t\n\"car insurance $180\"\t180\tCar insurance\tInsurance\ttoday\t\n\"groceries and some clothes at Target $150\"\t150\tTarget\tShopping\ttoday\tgroceries and clothes (ask user to split or pick)\n\"got reimbursed $45 for work lunch\"\t-45\tWork\tDining\ttoday\treimbursement\nAmbiguous Categories\n\nWhen a vendor could match multiple categories (e.g., \"Walmart\" could be Groceries or Shopping):\n\nBest-guess first: Pick the most likely category based on context\nConfirm with user: \"I logged $85 at Walmart as Groceries — is that right, or was this more of a Shopping trip?\"\nRemember preferences: If the user corrects, note the preference for future entries\n\nWhen no category matches at all, use Miscellaneous and tell the user: \"Logged under Miscellaneous — want me to put this in a specific category?\"\n\n2. Commands\n/add — Log an Expense\n\nLog an expense explicitly.\n\nUsage: /add [category] [date] [notes]\n\nImplementation: Run the add-expense script:\n\nbash skills/expense-tracker/scripts/add-expense.sh \"\" \"\" \"\" \"\"\n\n\nExamples:\n\n/add 45 Costco → logs $45 at Costco, auto-categorized, today's date\n/add 18.50 Chipotle Dining yesterday → $18.50 dining, yesterday\n/add -35 Amazon Shopping 2026-02-10 \"refund for headphones\" → refund\n\nMost of the time, users won't use /add — they'll just say \"spent $45 at Costco\" and you parse it.\n\n/spending — View Spending\n\nQuery expenses with optional filters.\n\nUsage: /spending [period] [category]\n\nImplementation: Run the query script:\n\nbash skills/expense-tracker/scripts/query.sh [--from DATE] [--to DATE] [--category CAT] [--format summary|detail|json]\n\n\nExamples:\n\n/spending → current month summary\n/spending this week → this week's expenses\n/spending Dining → all dining expenses this month\n/spending February detail → detailed February breakdown\n\"how much have I spent on groceries?\" → query with --category Groceries\n\"what did I spend last week?\" → query with appropriate date range\n\nFormat options:\n\nsummary (default) — totals by category\ndetail — itemized list with all fields\njson — raw JSON output\n/budget — Budget Status\n\nCheck spending against budget limits.\n\nUsage: /budget [month]\n\nImplementation: Run the budget check script:\n\nbash skills/expense-tracker/scripts/budget-check.sh [YYYY-MM]\n\n\nExamples:\n\n/budget → current month budget status\n/budget 2026-01 → January budget review\n\"how's my budget looking?\" → run budget check\n\nAlso supports adjusting budgets:\n\n\"set my dining budget to $400\" → update references/budgets.json using jq --arg (never interpolate user values into jq code directly)\n\"what's my grocery budget?\" → read from budgets.json\n/categories — View/Manage Categories\n\nShow available categories or recategorize expenses.\n\nExamples:\n\n/categories → list all categories\n/categories Dining → show Dining keywords and recent expenses\n\"move expense #12 to Entertainment\" → update ledger entry's category\n3. Category Auto-Matching\n\nUse references/categories.json to match vendors to categories. The matching algorithm:\n\nExact keyword match: Check if vendor name (lowercased) contains any keyword\nPartial match: Check if any keyword is a substring of the vendor name\nContext clues: Use surrounding words — \"lunch at\" → Dining, \"filled up at\" → Gas/Transport\nFallback: Miscellaneous\nAvailable Categories\n\nGroceries, Dining, Gas/Transport, Subscriptions, Health/Fitness, Entertainment, Shopping, Utilities, Housing, Personal Care, Education, Gifts, Travel, Insurance, Pets, Miscellaneous.\n\nPriority Order (when multiple match)\nMost specific keyword wins (\"Costco gas\" → Gas/Transport over Groceries)\nContext from user's message\nUser's historical pattern for that vendor\nAsk the user\n4. Budget Tracking\n\nBudget configuration lives in references/budgets.json. The user edits this to set their limits.\n\nAlert Thresholds\nThreshold\tEmoji\tAction\n< 50%\t⚪\tNo alert\n50–79%\t🟢\tInformational only\n80–99%\t🟡\tProactive warning: \"Heads up — Dining is at 85% of your $300 budget\"\n≥ 100%\t🔴\tAlert: \"You've exceeded your Dining budget ($312 / $300)\"\nWhen to Alert\nOn every expense: After logging, silently check the category budget. Only speak up at 80%+ threshold.\nOn /budget command: Show full breakdown with all categories.\nWeekly: If generating a weekly report, include budget status section.\nProactive Budget Warnings\n\nAfter logging an expense that pushes a category past 80%, add a note:\n\n✅ Expense #24: $45.00 at Olive Garden (Dining) on 2026-02-17 ⚠️ Heads up — Dining is now at $275 / $300 (92%) for February.\n\nAfter exceeding 100%:\n\n✅ Expense #25: $38.00 at Thai Palace (Dining) on 2026-02-19 🔴 Dining has exceeded your February budget: $313 / $300 (104%)\n\n5. Report Generation\nWeekly Report\n\nUse templates/weekly-report.md as a guide. Generate when the user asks \"weekly report\", \"how'd I do this week\", etc.\n\nTo generate, run query.sh for the week's date range, then format the results using the template structure:\n\n# Get this week's data\nbash skills/expense-tracker/scripts/query.sh --from 2026-02-10 --to 2026-02-16 --format json\n\n# Get last week for comparison\nbash skills/expense-tracker/scripts/query.sh --from 2026-02-03 --to 2026-02-09 --format json\n\n# Get budget status\nbash skills/expense-tracker/scripts/budget-check.sh\n\n\nInclude: category breakdown, top expenses, budget status, week-over-week trend.\n\nMonthly Report\n\nUse templates/monthly-report.md as a guide. Generate for \"monthly report\", \"how'd February go\", end-of-month reviews.\n\n# Current month data\nbash skills/expense-tracker/scripts/query.sh --from 2026-02-01 --to 2026-02-28 --format json\n\n# Previous month for comparison\nbash skills/expense-tracker/scripts/query.sh --from 2026-01-01 --to 2026-01-31 --format json\n\n# Budget check\nbash skills/expense-tracker/scripts/budget-check.sh 2026-02\n\n\nInclude: full category breakdown, top expenses, weekly breakdown, month-over-month comparison, savings rate (if income is set in budgets.json).\n\n6. Edge Cases\nRefunds\nDetect words: \"refund\", \"returned\", \"got back\", \"credit\", \"reimbursement\"\nStore as negative amount: add-expense.sh -35 \"Shopping\" \"Amazon\" \"2026-02-15\" \"refund\"\nRefunds reduce the category total in budget calculations\nSplitting Expenses\n\"Split $80 dinner with Sarah\" → log $40 (user's half)\n\"Split 3 ways: $120 at the bar\" → log $40\nConfirm the split: \"Logging your share: $40 at the bar (Dining). That right?\"\nRecurring Expenses\nThis skill doesn't auto-schedule recurring expenses\nWhen the user says \"Netflix again\" or \"monthly gym payment\", treat as a new entry\nThe AI can note: \"Want me to remind you about this next month?\" (but don't auto-create)\nMulti-Item Purchases\n\"Spent $150 at Target on groceries and clothes\" → Ask user whether to log as one entry or split\nIf split: create separate entries per category\nIf single: pick the dominant category or ask which one\n\"Bought lunch and a coffee at Panera, $22\" → single Dining entry is fine (same category)\nMulti-Currency (Optional)\nIf the user mentions foreign currency: \"spent €50 in Paris\"\nLog the original amount and note the currency: add-expense.sh 55 \"Travel\" \"Paris restaurant\" \"2026-02-15\" \"€50 EUR\"\nConvert to USD for budget purposes (ask user for rate or use approximate)\nDefault behavior: assume USD unless told otherwise\nCorrections\n\"Actually that Costco trip was $52, not $45\" → Find the recent Costco entry, update amount\n\"Delete expense #12\" → Remove from ledger using jq --argjson id 12 'map(select(.id != $id))' — always use --arg/--argjson, never interpolate IDs into filter strings\n\"Move #12 to Dining\" → Update category field\nZero-Expense Days\nDon't alert on no-spend days unless asked\nIn reports, show $0 days as positive (savings!)\n7. Conversational Patterns\n\nThe AI should handle these naturally without requiring commands:\n\nUser Says\tAI Action\n\"spent $45 at Costco\"\tParse → add expense → confirm → check budget\n\"how much have I spent this month?\"\tRun query.sh for current month → format summary\n\"am I over budget?\"\tRun budget-check.sh → report status\n\"weekly report\"\tGenerate weekly report from template\n\"what did I spend on food?\"\tQuery Groceries + Dining categories\n\"I got a $20 refund from Amazon\"\tLog negative amount → confirm\n\"split a $90 dinner with Jake\"\tCalculate half → log $45 → confirm\n\"that last one should be Entertainment, not Shopping\"\tUpdate most recent entry's category\n\"set grocery budget to $700\"\tUpdate budgets.json\n\"how much is left in my dining budget?\"\tCalculate: limit - spent this month\n\"show me everything from last week\"\tQuery with date range, detail format\n\"what's my biggest expense this month?\"\tQuery + sort by amount\n\"cancel that last expense\"\tDelete most recent ledger entry\n\"spent $5.50 at starbucks yesterday\"\tParse date as yesterday → add expense\n\"vet bill was $280\"\tLog as Pets category\n\"car insurance came out, $180\"\tLog as Insurance category\n\"I spent like 50 bucks at Target\"\tLog $50, confirm amount approximation\n\"got reimbursed $45 from work\"\tLog as negative (reimbursement)\n\"how much did I spend on food this month?\"\tQuery Groceries + Dining combined\n\"compare this month to last month\"\tGenerate month-over-month comparison\n8. Example Full Interaction\nUser: spent $45 at Costco\nAI: ✅ Expense #1: $45.00 at Costco (Groceries) on 2026-02-17\n\nUser: grabbed lunch at Chipotle for $12.50\nAI: ✅ Expense #2: $12.50 at Chipotle (Dining) on 2026-02-17\n\nUser: $150 at Target yesterday\nAI: I logged $150 at Target as **Shopping** — was this groceries or more of a general shopping trip?\nUser: shopping\nAI: ✅ Expense #3: $150.00 at Target (Shopping) on 2026-02-16\n\nUser: how's my budget looking?\nAI:\n=== Budget Check: 2026-02 ===\n 🟢 OK Groceries $345 / $600 (58%)\n 🟡 WARN Dining $248 / $300 (83%)\n 🟢 OK Shopping $280 / $300 (93%)\n ⚪ LOW Gas/Transport $85 / $250 (34%)\n ...\n TOTAL: $1,245.00 / $4,950 (25%)\n\n⚠️ Heads up — Dining is at 83% and Shopping is at 93% of your February budget.\n\nUser: I got a refund from Amazon for $35\nAI: ✅ Refund #4: $35.00 from Amazon (Shopping) on 2026-02-17\n Shopping is now at $245 / $300 (82%) for February.\n\nUser: weekly report\nAI: [generates formatted weekly report from template]\n\nUser: set my dining budget to $400\nAI: Updated Dining budget: $300 → $400 for this month. You're now at $248 / $400 (62%) — much more breathing room! 🟢\n\n9. Data Format Reference\nLedger Entry (expenses/ledger.json)\n[\n {\n \"id\": 1,\n \"amount\": 45.00,\n \"category\": \"Groceries\",\n \"vendor\": \"Costco\",\n \"date\": \"2026-02-17\",\n \"notes\": \"\",\n \"created_at\": \"2026-02-17T23:32:00Z\"\n },\n {\n \"id\": 2,\n \"amount\": -35.00,\n \"category\": \"Shopping\",\n \"vendor\": \"Amazon\",\n \"date\": \"2026-02-17\",\n \"notes\": \"refund for headphones\",\n \"created_at\": \"2026-02-17T23:45:00Z\"\n }\n]\n\nKey Rules\nIDs: Incrementing integers, never reused\nAmounts: Always numbers. Positive = expense, negative = refund\nDates: ISO 8601 YYYY-MM-DD\nCategories: Must match a name in references/categories.json\ncreated_at: UTC timestamp of when the entry was created\n10. Script Reference\n\nAll scripts are in skills/expense-tracker/scripts/ and must be run with bash:\n\n# Add an expense\nbash skills/expense-tracker/scripts/add-expense.sh 45 \"Groceries\" \"Costco\" \"2026-02-17\" \"weekly groceries\"\n\n# Query expenses\nbash skills/expense-tracker/scripts/query.sh --from 2026-02-01 --to 2026-02-28 --category Dining --format summary\n\n# Check budget\nbash skills/expense-tracker/scripts/budget-check.sh 2026-02\n\nScript Arguments\n\nadd-expense.sh [date] [notes]\n\namount — number (negative for refunds)\ncategory — category name from categories.json\nvendor — merchant name\ndate — YYYY-MM-DD (default: today)\nnotes — optional description\n\nquery.sh [--from DATE] [--to DATE] [--category CAT] [--vendor TEXT] [--format FMT]\n\n--from — start date (inclusive)\n--to — end date (inclusive)\n--category — filter by category name\n--vendor — filter by vendor (partial match, case-insensitive)\n--format — summary (default), detail, or json\n\nbudget-check.sh [YYYY-MM]\n\nOptional month argument (default: current month)\nExit code 0 = all OK, exit code 1 = at least one category ≥ 80%" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/nicholasrae/nicholasrae-expense-tracker", "publisherUrl": "https://clawhub.ai/nicholasrae/nicholasrae-expense-tracker", "owner": "nicholasrae", "version": "1.0.3", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/nicholasrae-expense-tracker", "downloadUrl": "https://openagent3.xyz/downloads/nicholasrae-expense-tracker", "agentUrl": "https://openagent3.xyz/skills/nicholasrae-expense-tracker/agent", "manifestUrl": "https://openagent3.xyz/skills/nicholasrae-expense-tracker/agent.json", "briefUrl": "https://openagent3.xyz/skills/nicholasrae-expense-tracker/agent.md" } }