Agent skills

Taxbit Skills is a free package of agent skills that teaches your AI coding agent how the Taxbit API and React SDK work: real endpoints and fields, the right auth tokens, and Taxbit's security practices for tax data. Your agent loads a skill automatically when you work on a Taxbit integration.

It works with Claude Code, Cursor, GitHub Copilot, Windsurf and 40+ other agents.

Install

Run this in your project to add both skills to every supported agent:

npx skills add taxbit-shared/taxbit-skills

Or, in Claude Code, install the plugin:

/plugin marketplace add taxbit-shared/taxbit-skills

/plugin install taxbit@taxbit-skills

The plugin also adds /taxbit:api and /taxbit:react-sdk slash commands. You can use both install methods; they don't conflict.

Available skills

📘

The React SDK isn't a general API client

@taxbit/react-sdk does one job: it renders Taxbit's tax documentation forms in your React app and submits them. Everything else, including requesting the token the SDK needs, sending transactions, reading gains and receiving webhooks, goes through the REST API from your server. Most SDK integrations need both skills.

Which skill do I need?

Webhooks

The API skill covers Taxbit webhooks end to end, so your agent can write a production-ready handler, not just a route that returns 200.

Events

Your agent knows every event, when it fires, and the exact shape of its payload:

There's no separate "form submitted" event. A submission changes the account owner's status, which sends ACCOUNT_OWNER_TAX_DOCUMENTATION_STATUS.

What your agent gets right

• Signature verification. Checks x-taxbit-signature on every delivery the way Taxbit signs it: HMAC-SHA256 over the re-serialized JSON, base64, with the v1= prefix, compared in constant time. It accepts any of several signatures, so your handler keeps working while a signing secret is rotated.
• Safe responses. Answers a bad signature or malformed payload with 400. It never returns 401 or 407, which disable your subscription until Taxbit re-enables it, even when they come from a WAF or gateway in front of your endpoint. It also avoids 403, which Taxbit doesn't retry.
• Fast acknowledgement. Queues each event durably, returns 2xx, then processes it, so slow work doesn't cause timeouts and retries.
• Duplicates and ordering. Delivery is at least once and in no guaranteed order. Your agent makes handlers idempotent, orders events by their own date fields rather than the delivery timestamp, and ignores fields and event types it doesn't recognize.
• Payload details. Reads events from the data array, checks that optional sections exist before reading them, compares the full tax documentation status with the last one you stored before acting, and handles INVENTORY_UPDATE events that have no transaction IDs because transactions were deleted.
• Traceability. Logs x-trace-id on every delivery, which Taxbit Support needs to trace or replay one.

Setup, testing and troubleshooting

Webhook subscriptions aren't self-serve: your implementation manager sets them up. Your agent can tell you what to send them (your HTTPS endpoint, the events you want, and any IP allowlist or basic auth in front of the endpoint), walk you through testing with a test subscription before go-live, and diagnose common problems, such as deliveries that suddenly stop or signatures that don't verify.

Example prompts

You don't need to name the skill. Describe the task and your agent loads the right one.

API

• "Write a Node service that gets a Taxbit tenant-scoped token, caches it, and refreshes it before it expires."
• "Create an account owner and their first account in Taxbit from our User model."
• "Send our trade history to Taxbit as transactions, then read back realized gains for 2026."
• "Validate a user's name and TIN with Taxbit before we save their W-9."
• "Back off and retry correctly when Taxbit returns a 429."

API: webhooks

• "Write an Express handler for Taxbit webhooks that verifies the signature and queues each event."
• "Update our user's tax status when we get an ACCOUNT_OWNER_TAX_DOCUMENTATION_STATUS event, and email them only if they have a new issue to fix."
• "Show a user's 1099 in our app as soon as Taxbit sends FORM_STATUS_UPDATE with Generated."
• "Refresh an account's gains when we receive INVENTORY_UPDATE."
• "Make our webhook handler safe to receive the same event twice."
• "We stopped receiving Taxbit webhooks. What should we check?"
• "What do I need to send my implementation manager to set up webhooks?"

React SDK

• "Add a W-9/W-8 collection page to our Next.js app with the Taxbit React SDK, and show a confirmation when it's submitted."
• "Only show the tax form if the user hasn't completed their documentation yet."
• "Show a banner when a user has W-8 issues to cure, and open the curing flow from it."
• "Let users download a PDF of the W-9 they submitted."
• "Theme the Taxbit questionnaire to match our brand colors."
• "Upgrade us from @taxbit/react-sdk 5.x to 6.x."

Both

• "Add an endpoint that requests a Taxbit account owner token, and use it to render the questionnaire on our tax settings page."
• "Recover when the account owner token expires while the user still has the form open."

Security

Both skills tell your agent to keep client_secret and tokens on your server, read them from the environment instead of asking you to paste them into the chat, and never log TINs or other personal data. Always review generated code and test in your sandbox before you ship.

Updates and feedback

To get the latest skills, run npx skills add taxbit-shared/taxbit-skills again, or /plugin marketplace update taxbit-skills in Claude Code. See what changed in the changelog.

If your tool doesn't support skills, point it at llms.txt.

Found something wrong or missing? Open an issue or contact Taxbit Support.