🔧awx-best-practices
- プラグイン
- airwallex-agentos
- ソース
- GitHub で見る ↗
説明
フォールバック用 Airwallex スキル — Airwallex CLI または Airwallex MCP サーバーと連携して動作します。 **次のような場合に使用:** 専用のワークフロースキルが該当タスクに合致しない場合に限り使用してください。 アドホックな操作（list・get・update・delete・void・cancel）、Airwallex API に関する一般的な質問、トラブルシューティング、およびワークフロースキルがカバーしていないドメイン（ペイメントリンク、返金、異議申し立て、支出管理、財務レポートなど）に対応します。 **注意事項:** このスキルをワークフロースキルと同時にロードしないでください — 各ワークフロースキルはそれ自体で完結しています。 以下の用途には、それぞれ対応する専用スキルを使用してください: - 請求書 / 課金 / クーポン / メーター / クレジットノート → `contract-to-billing` - サプライヤー / 受取人（beneficiary） → `beneficiary-creation` - カード → `card-provisioning` - 残高 / 外国為替（FX） / キャッシュフロー → `manage-cashflow`
原文を表示
Fallback Airwallex skill — works with the Airwallex CLI or the Airwallex MCP server. Use ONLY when no dedicated workflow skill matches the task. Covers ad-hoc operations (list, get, update, delete, void, cancel), general Airwallex API questions, troubleshooting, and domains not covered by a workflow skill (payment links, refunds, disputes, spend management, financial reports). Do NOT load this skill alongside a workflow skill — each workflow skill is self-contained. For invoices/billing/coupons/meters/credit notes use contract-to-billing, for suppliers/beneficiaries use beneficiary-creation, for cards use card-provisioning, for balances/FX/cashflow use manage-cashflow.
ユースケース
- ✓専用スキルが該当タスクに合致しないとき
- ✓アドホックな操作を実行するとき
- ✓Airwallex APIに関する質問があるとき
- ✓トラブルシューティングが必要なとき
- ✓ペイメントリンク・返金・異議申し立てに対応するとき
本文（日本語訳）
Airwallex ベストプラクティス
Airwallexタスク向けのフォールバックスキル。専用のワークフロースキルが存在しない場合にのみ使用すること。 各ワークフロースキル（beneficiary-creation、card-provisioning、contract-to-billing、manage-cashflow）は独立した完結型です — これらと本スキルを同時にロードしないでください。
使用する場面
- アドホック操作（list、get、update、delete、void、cancel、deactivate）
- Airwallex APIに関する一般的な質問やトラブルシューティング
- 専用のワークフロースキルがカバーしていないドメイン（支払いリンク、返金、異議申立、支出管理、財務レポートなど）
代わりにワークフロースキルを使用する場面
| タスク | スキル |
|---|---|
| 発注書 / 契約 / 見積もりから請求書を作成 | contract-to-billing |
| クーポン、メーター、使用イベント、クレジットノート | contract-to-billing |
| サプライヤーのオンボーディング / 受取人の作成 | beneficiary-creation |
| 法人カードのプロビジョニング | card-provisioning |
| キャッシュポジション、FX、残高、リバランス | manage-cashflow |
ワークフロースキルが該当する場合は、そのスキルを使用してください — 本スキルと同時にロードしないでください。
対応範囲外 — 拒否してリダイレクトする
APIコールを組み合わせてこれらを実行しようとしないでください。 その機能が利用できない旨をはっきりと伝え、最も近い代替手段を説明したうえで、対応を申し出てください。
| リクエストのパターン | 対応範囲外の理由 | リダイレクト先 |
|---|---|---|
| 「トランザクションレポート」「今月の全取引」「台帳エクスポート」 | いずれのスキルも会計グレードのトランザクションレポートを生成しない | キャッシュポジション・売掛金・支払義務には manage-cashflow を案内 |
| 「消込 / 照合（Reconciliation）」「損益計算書」「貸借対照表」「会計レポート」 | 会計機能はagentの対応範囲外 | 上記に同じ |
| 「予測（Forecast）」「ヘッジ戦略」「FX予測」 | Agentが提供できるのは参考スポットレートのみ | 現在のエクスポージャーと参考FXレートには manage-cashflow を案内 |
| 「利回り」「投資アドバイス」「遊休資金」「自動チャージ」「レートをロックすべきか？」 | 金融アドバイスまたは未サポートのトレジャリー操作 | 現在の残高・支払義務・参考FXレート（情報提供目的のみ）には manage-cashflow を案内 |
環境のクイックスタート
認証、ディスカバリ、書き込み安全性、ページネーション、エラーハンドリングなど各サーフェスの詳細は references/surface-quickstart.md を参照してください。
運用ルール
- 不明な情報を捏造・推測しないこと。 必須フィールドに不確かなものがある場合は — 処理を止めてユーザーに確認する。
- 常に最新データを取得すること — 各ステップの直前に再取得する。
- ユーザーがファイルや添付物を提供した場合は、それを一次情報源として扱うこと（ライブデータを求められた場合を除く）。
- 意図が曖昧なリクエストには、実行前にアクションを確認すること。
- 未サポートの機能を過度に主張しないこと。 送金、ペイアウト、FX実行、PAN/CVVの取得、会計レポート、消込は即座に断り、何が利用できないかを明示し、最も近い代替手段を案内する。
- 金融アドバイスを提供しないこと。 利回り、投資商品、自動チャージ、ヘッジ戦略、FX予測、レートロックを推奨しない。トレジャリーに関する質問は manage-cashflow にリダイレクトし、FXに関する情報は情報提供目的であること・参考値であることを明確に示す。
- サポート対象と非対象のリクエストを分けて処理すること。 サポート対象の部分を完了させ、設定できなかった内容を明確に伝える。
- ユーザー向け出力では生のIDより人間が読めるラベルを優先すること。 生のシステムIDの代わりに、人間が読めるビジネスラベル（顧客名、商品名、受取人名、カードのニックネームなど）を可能な限り表示する。IDを表示するのは、後続アクション、確認、トラブルシューティングで業務上必要な場合、またはユーザーが明示的に要求した場合のみとする。
Airwallexの主要コンセプト
- ウォレットは1つ、通貨は複数。「AUD残高」と表現し、「AUDウォレット」とは言わない。
- 請求書（Invoice）= 売掛金（入金）。 ユーザーが顧客に対して発行するもの。
- 支払請求（Bill）= 買掛金（出金）。 ユーザーがサプライヤーに支払うべきもの。
- FXコンバージョンは1つのウォレット内で実行される — ウォレット間ではない。
影響の大きい操作
これらは不可逆または影響の大きい操作です。 いずれかを実行する前に必ず: (1) 環境（sandboxかproductionか）を確認・明示する、(2) 操作の影響を説明する、(3) ユーザーの明示的な確認を得る。
| 操作 | CLI | MCP | 備考 |
|---|---|---|---|
| 請求書のVoid | airwallex --confirm invoices void <id> |
billing-invoice voidツールを呼び出す | 不可逆。FINALIZED+UNPAIDのみ。 |
| 下書き請求書の削除 | airwallex --confirm invoices delete <id> |
未公開 | DRAFTのみ。 |
| 請求書のファイナライズ | airwallex --confirm invoices finalize <id> |
billing-invoice finalizeツールを呼び出す | 不可逆 — 以降は編集不可。 |
| 請求書を支払済みにする | airwallex --confirm invoices mark-as-paid <id> |
billing-invoice mark-as-paidツールを呼び出す | FINALIZEDであること。Airwallex外で支払われた場合に使用。 |
| サブスクリプションのキャンセル | airwallex --confirm subscriptions cancel <id> |
subscription cancelツールを呼び出す | スキーマでフラグを確認すること。 |
| カードの無効化 | cards update <id> ボディ {"status":"INACTIVE"} |
card-updateツールで card_status: INACTIVE を指定 |
可逆。ここで設定できないステータスについては references/api_traps.md を参照。 |
| カードのクローズ | cards update <id> ボディ {"status":"CLOSED"} |
card-updateツールで card_status: CLOSED を指定 |
永続的。 |
| FXコンバージョン | Airwallexダッシュボードのみ | Airwallexダッシュボードのみ | いずれのサーフェスからも実行不可。 |
| クレジットノートのファイナライズ | airwallex --confirm credit-notes finalize <id> |
クレジットノートツールは未公開 — CLIまたはAirwallexダッシュボードを使用 | 不可逆。 |
| クレジットノートのVoid | airwallex --confirm credit-notes void <id> |
クレジットノートツールは未公開 — CLIまたはAirwallexダッシュボードを使用 | 不可逆。 |
| グローバルアカウントのクローズ | airwallex --confirm global-accounts close <id> |
公開されていればglobal-account closeツールを呼び出す | 永続的。 |
| カード保有者の削除 | airwallex --confirm cardholders delete <id> |
公開されていればcardholder deleteツールを呼び出す | アクティブなカードがないことを確認すること。 |
エラーハンドリング
| 状況 | 対応 |
|---|---|
| 必須フィールドが欠けているまたは曖昧 | 処理を止め、不足箇所を列挙し、ユーザーに確認する |
| APIエラー | エラー全文を表示し、ユーザーに確認する |
| APIバリデーションエラー | references/api_traps.md を確認する。CLIを使用している場合は、airwallex <resource> <action> --api-schema-only を実行してボディ構造を検証する。MCPサーバーを使用している場合は、ツールの入力スキーマを再確認する。 |
| 401 / 認証の期限切れ | CLIを使用している場合は、一度リトライする（自動更新）。リトライが失敗した場合は、ユーザーに環境を確認し、即座に auth login（または --prod）を自分で実行し、auth whoami で確認後、処理を再開する。MCPサーバーを使用している場合は、サーバーが自動でトークンを更新する。ツールが引き続き401を返す場合はOAuthグラントが失効しているため、ユーザーにMCPサーバーの再認可を依頼する。 |
| 重複が検出された | 詳細を表示し、ユーザーに選択させる |
| 部分的な完了 | 成功した内容（IDを含む）と失敗した内容を報告する |
リファレンス
- references/api_traps.md — スキーマ / マニフェストが示す内容を超えた、非自明なボディ制約。
- CLIを使用している場合は、コマンドのディスカバリに
airwallex --tree --compact [group]、コマンドスキーマ（必須フラグを含む）の確認にairwallex <resource> <action> --api-schema-onlyを使用する。 - Airwallex API Introduction
原文（English）を表示
Airwallex Best Practices
Fallback skill for Airwallex tasks. Use only when no dedicated workflow skill fits. Each workflow skill (beneficiary-creation, card-provisioning, contract-to-billing, manage-cashflow) is self-contained — do NOT load this skill alongside them.
When to use
- Ad-hoc operations (list, get, update, delete, void, cancel, deactivate)
- General Airwallex API questions or troubleshooting
- Payment links, refunds, disputes, spend management, financial reports, and other domains not covered by a dedicated workflow skill
Use a workflow skill instead
| Task | Skill |
|---|---|
| Create invoice from PO/contract/quote | contract-to-billing |
| Coupons, meters, usage events, credit notes | contract-to-billing |
| Onboard suppliers / create beneficiaries | beneficiary-creation |
| Provision corporate cards | card-provisioning |
| Cash position, FX, balances, rebalancing | manage-cashflow |
If a workflow skill matches, use that skill instead — do NOT load this one alongside it.
Out of scope — refuse and redirect
Do NOT attempt to fulfill these by aggregating API calls. State plainly that the capability is not available, explain the closest alternative, and offer to help with it.
| Request pattern | Why out of scope | Redirect |
|---|---|---|
| "Transaction report", "all transactions this month", "ledger export" | No skill produces accounting-grade transaction reports | Offer manage-cashflow for cash position, receivables, obligations |
| "Reconciliation", "P&L", "balance sheet", "accounting report" | Accounting functions outside agent capability | Same as above |
| "Forecast", "hedging strategy", "FX prediction" | Agent provides indicative spot rates only | Offer manage-cashflow for current exposure and indicative FX rates |
| "Yield", "investment advice", "idle funds", "automated top-up", "should I lock a rate?" | Financial advice or unsupported treasury action | Offer manage-cashflow for current balances, obligations, and informational indicative FX only |
Environment quickstart
See references/surface-quickstart.md for full per-surface details (auth, discovery, write safety, pagination, error handling).
Operational rules
- NEVER fabricate or assume missing information. If any required field is uncertain — STOP and ask the user.
- Always fetch fresh data — re-fetch before every step.
- If the user supplied a file or attachment, treat it as primary ground truth unless they ask for live data.
- For ambiguous-intent requests, confirm the action before starting.
- Never overclaim unsupported capabilities. Transfers, payouts, FX execution, PAN/CVV retrieval, accounting reports, reconciliation: refuse immediately, state what is not available, offer the closest alternative.
- Do not provide financial advice. Never recommend yield, investment products, automated top-ups, hedging strategy, FX prediction, or rate-locking. For treasury questions, redirect to manage-cashflow and keep any FX discussion informational and clearly labelled as indicative.
- Split supported and unsupported asks. Complete the supported portion and clearly state what was not configured.
- Prefer business labels over raw IDs in user-facing output. Show human-readable business labels (customer names, product names, beneficiary names, card nicknames, etc.) instead of raw system IDs whenever possible. Only show IDs when they are operationally necessary for follow-up actions, verification, troubleshooting, or when the user explicitly asks for them.
Core Airwallex concepts
- One wallet, multiple currencies. Say "AUD balance" — never "AUD wallet."
- Invoices = receivables (money in). Issued BY the user TO their customers.
- Bills = payables (money out). Money the user owes to suppliers.
- FX conversions happen within one wallet — not between wallets.
Consequential operations
These are irreversible or high-impact. Before executing ANY of them: (1) confirm and state the environment (sandbox vs production), (2) explain the effect, (3) get explicit user confirmation.
| Operation | CLI | MCP | Notes |
|---|---|---|---|
| Void invoice | airwallex --confirm invoices void <id> |
invoke the billing-invoice void tool | Irreversible. FINALIZED+UNPAID only. |
| Delete draft invoice | airwallex --confirm invoices delete <id> |
not exposed | DRAFT only. |
| Finalize invoice | airwallex --confirm invoices finalize <id> |
invoke the billing-invoice finalize tool | Irreversible — cannot edit after. |
| Mark invoice paid | airwallex --confirm invoices mark-as-paid <id> |
invoke the billing-invoice mark-as-paid tool | Must be FINALIZED. Use when paid outside Airwallex. |
| Cancel subscription | airwallex --confirm subscriptions cancel <id> |
invoke the subscription cancel tool | Check flags via schema. |
| Deactivate card | cards update <id> body {"status":"INACTIVE"} |
card-update tool with card_status: INACTIVE |
Reversible. See references/api_traps.md for which statuses are NOT settable here. |
| Close card | cards update <id> body {"status":"CLOSED"} |
card-update tool with card_status: CLOSED |
Permanent. |
| FX conversion | Airwallex Dashboard only | Airwallex Dashboard only | Not executable via either surface. |
| Finalize credit note | airwallex --confirm credit-notes finalize <id> |
credit-note tools not exposed — use the CLI or the Airwallex Dashboard | Irreversible. |
| Void credit note | airwallex --confirm credit-notes void <id> |
credit-note tools not exposed — use the CLI or the Airwallex Dashboard | Irreversible. |
| Close global account | airwallex --confirm global-accounts close <id> |
invoke the global-account close tool if exposed | Permanent. |
| Delete cardholder | airwallex --confirm cardholders delete <id> |
invoke the cardholder delete tool if exposed | Ensure no active cards. |
Error handling
| Situation | Action |
|---|---|
| Required field missing or ambiguous | STOP, list gaps, ask user |
| API error | Show full error, ask user |
| API validation error | Check references/api_traps.md. IF using the CLI, THEN also run airwallex <resource> <action> --api-schema-only to verify body structure. ELSE IF using the MCP server, THEN re-inspect the tool's input schema. |
| 401 / auth expired | IF using the CLI, THEN retry once (auto-refresh). If retry fails, ask the user which environment, immediately execute auth login (or --prod) yourself, confirm with auth whoami, then resume. ELSE IF using the MCP server, THEN the server refreshes tokens automatically; if a tool keeps returning 401, the OAuth grant has been revoked — ask the user to re-authorize the MCP server. |
| Duplicate detected | Show details, let user choose |
| Partial completion | Report what succeeded (with IDs) and what failed |
References
- references/api_traps.md — non-obvious body constraints beyond what the schema/manifest surfaces.
- IF using the CLI, THEN
airwallex --tree --compact [group]for command discovery andairwallex <resource> <action> --api-schema-onlyfor command schemas (including required flags). - Airwallex API Introduction
原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。