Boon agent skill file

Full Boon agent skill file generated from skill/boon/SKILL.md.

Boon agent skill file

This page is generated from the repository source of truth at skill/boon/SKILL.md. The raw hosted copy is also available at /skill.md, /.well-known/skills/boon.md, and /.well-known/agent-skills/boon.md.

Skill metadata

name: boon
version: "0.2.0"
description: >
  Retroactive USDC gratitude on Base. Use when the operator wants to propose,
  approve, send, explain, or help claim small boons for useful human or agent
  contributions. Triggers include "boon alice", "thank github:alice", "send 5
  USDC to x:bob for that review", "run weekly boons", "who should I boon this
  week?", and "help me claim a boon". Supports proposal-only, execution, and
  claim-help modes. Never auto-sends funds without explicit approval.
triggers:
  - "boon alice"
  - "thank github:alice"
  - "send 5 USDC to x:bob for that review"
  - "run weekly boons"
  - "who should I boon this week?"
  - "help me claim a boon"
  - "what is Boon?"
tags:
  - gratitude
  - usdc
  - base
  - tipping
  - escrow
  - agent-rewards
  - social-handles
credentials:
  - name: BOON_CONTRACT
    description: Base contract address for the Boon settlement contract.
    required: false
    storage: env
  - name: BASE_RPC_URL
    description: Base RPC URL used by CLI or adapters for read/simulate/write paths.
    required: false
    storage: env
  - name: BOON_WORKER_URL
    description: Optional claim/OAuth worker URL for recipient-link flows.
    required: false
    storage: env
metadata:
  compatibility:
    chains: [base]
    settlementAsset: USDC
    modes: [proposal, execution, claim-help, weekly-review]
    requiresHumanApprovalForWrites: true

Skill body

Boon — retroactive gratitude settlement

Boon is for sending small USDC thank-yous for concrete useful work. The agent can identify candidates, propose amounts, prepare an execution summary, and execute only after explicit operator approval. Settlement is intentionally narrow: Base mainnet, USDC only, canonical social handles, public receipts, and bounded operator spend.

Contract

This skill guarantees:

Boon requests default to proposal mode unless the operator provides an exact canonical handle, amount, note, chain, Boon contract, and final approval.
Any write path preserves the Base-mainnet/USDC-only settlement boundary and uses tip(bytes32 handleHash, string displayHandle, uint256 amount, string note).
Recipient claim-help stays free and educational; never charge to receive, view, link, or claim escrowed boons.
Uncertain identity, evidence, artifact, budget, cooldown, or credential state is surfaced explicitly as needs_check instead of guessed.
Private keys, arbitrary token addresses, non-Base chains, hidden receipts, and autonomous reward distribution are refused or reshaped into safe proposal mode.

Critical rules

Never auto-send funds. A write requires an explicit canonical handle, amount, note, chain, contract, and final approval from the operator.
USDC on Base only. The v1 contract pins USDC at construction; do not pass arbitrary token addresses or suggest other chains.
Normalize before hashing. Canonical handles are github:<user> or x:<user>. Use the local CLI or @boon/normalize; never invent a hash.
Use the current contract shape. tip(bytes32 handleHash, string displayHandle, uint256 amount, string note). The token is immutable in the contract. Do not use older tip(handle, token, amount, note) guidance.
Provider is explicit in link vouchers. Link vouchers sign providerHash = keccak256(utf8(provider)) and handleHash = keccak256(utf8(canonicalHandle)) with recipient, nonce, and deadline. Keep the provider prefix in the canonical handle too.
Evidence first. Prefer a concrete artifact in the note: PR, issue, review, cast/post, task ID, transaction, skill/library, or short source tag.
No vague payroll. Boon is retroactive gratitude, not salary, bounty escrow, task assignment, or an autonomous reward bot.
Refuse private keys. Use browser wallet consent, wallet adapters, or operator-managed signing. If write authority is missing, stop at proposal mode.
No claim tax. Recipient claim/help flows must stay free to view and use; do not put receiving, claiming, or viewing escrow behind a paid endpoint.
Surface uncertainty. If the handle, artifact, recipient, or evidence is ambiguous, ask for clarification or produce a proposal marked needs_check.

Mode selector

User intent	Mode	Action
”who should I boon?”, “run weekly boons”	Proposal	Gather evidence, rank candidates, no transaction.
”boon github:alice 5 USDC …”	Execution	Validate, preview, ask final approval, then run CLI/write path.
”thank them for this PR”	Proposal -> Execution	Resolve handle/artifact, propose note/amount, wait for approval.
”help me claim” / recipient questions	Claim-help	Explain OAuth + wallet link + claim path; no sender funds move.
”what is Boon?”	Explanation	Describe the product and safety model concisely.
”automatically tip everyone”	Refuse/reshape	Offer a proposal list; do not auto-execute.

Data model and conventions

Canonical identity

Handle: github:alice, x:bob
Provider: substring before : (github, x)
providerHash: keccak256(utf8(provider))
handleHash: keccak256(utf8(canonicalHandle))

When preparing link-voucher or claim guidance, preserve both facts:

canonicalHandle = "github:alice"
providerHash    = keccak256(utf8("github"))
handleHash      = keccak256(utf8("github:alice"))

The shared vector lives at test-vectors/link-voucher.json in the Boon repo. Use it as the cross-language source of truth for Link EIP-712 type, domain fields, hash convention, signature, and expected signer recovery.

Artifact/source note convention

Until a future contract version adds dedicated receipt fields, encode concise artifact references in note:

Source	Note prefix examples
GitHub PR / issue	`pr:owner/repo#42 — caught race in bundler`
Code review	`review:owner/repo#42 — security notes`
X / social post	`x:2055825024901378483 — risk warning`
Cast	`cast:<hash> — implementation advice`
Task / bounty	`task:123 — extra polish after approval`
Skill/library	`skill:boon — reusable workflow fix`
Transaction	`tx:0xabc… — verified rescue`

Keep notes short and human-readable. If a source ID is too long, include the stable short ID and put full evidence in the proposal text before execution.

Proposal mode

Use proposal mode when there is no explicit final amount + approval, or when the operator asks for weekly review.

1. Gather signal

Use available local/app context. Strong signals:

merged PRs, review comments, issue fixes, or small patches that unblocked work
precise technical/social feedback the operator accepted or acted on
agent/human work tied to a task, artifact, tx, skill, library, or diagnosis
risk warnings that prevented loss or rework
maintenance or polish that was useful but not formally bounty-paid

Weak signals to downrank or skip:

likes, generic praise, hype, vague agreement
work already fully compensated unless a bonus is clearly deserved
old events outside the review window unless the operator explicitly includes them
handles or identities that cannot be resolved confidently

2. Score candidates

Score each candidate 0-5 on:

Dimension	What to look for
Impact	Did it unblock, save time, reduce risk, or improve quality?
Evidence	Is there a concrete artifact/source?
Effort	Did the person invest meaningful time or expertise?
Fit	Is a small gratitude payment appropriate vs a bounty/invoice?
Freshness	Did it happen in the requested window?
Cooldown	Has this recipient already been boon’d recently?

Default filters:

review budget: 50 USDC unless operator settings say otherwise
single tip max: 25 USDC unless operator settings say otherwise
cooldown: 30 days per canonical handle unless operator overrides
suggested amounts: 2, 5, 10, 15, or 25 USDC; avoid false precision

3. Render proposals

Use this exact structure for weekly/proposal output:

Boons proposal for <period>:
  1. github:alice — 10 USDC
     note: "pr:owner/repo#42 — caught race in bundler"
     why: concrete review prevented a production bug
     evidence: <link or artifact id>
     status: ready
  2. x:bob — 5 USDC
     note: "x:2055825024901378483 — risk warning"
     why: useful public warning changed the plan
     evidence: <link or post id>
     status: needs_check: confirm this is the right handle
Total: 15 / 50 USDC review budget.
Next: approve, edit, or skip. No funds move until you approve exact rows.

Do not bury uncertainty. Mark rows as needs_check when identity or evidence is not strong enough for execution.

Execution mode

Only enter execution mode after the operator approves exact rows.

Preflight checklist

For every approved boon, verify or display:

chain: Base mainnet (8453)
settlement asset: USDC pinned by the contract
contract: Boon contract address, not an arbitrary target
canonical handle and handleHash
amount in USDC and smallest units
note length and artifact/source prefix when available
budget and cooldown status
whether execution will push to a linked wallet or escrow for claim, if known
command or transaction path that will be used

If any value is missing, do not execute. Ask for the missing value or switch back to proposal mode.

CLI execution

Before any execution, check readiness:

boon doctor

The CLI is agent-native. OWS is the only agent path: a funded OWS agent wallet. The operator connects an OWS wallet through boon wallet connect ows, sends a small amount of Base USDC to the printed agent address, sets an ows_key_... API token for the run, and boon tip spends from that wallet after the local budget/cooldown checks plus OWS policy checks. Stay on the boon ... CLI surface for Boon tipping.

boon wallet connect ows --wallet boon-agent
boon doctor
boon tip --dry-run <canonical-handle> <amount-usdc> "<note>"
boon tip --yes --approval-id <human-approved-policy-or-plan-id> <canonical-handle> <amount-usdc> "<note>"

OWS mode routes the agent’s USDC approval and Boon.tip() calls through the Boon-owned OWS adapter; the CLI never holds a raw private key. OWS evaluates the ows_key_... token’s attached policies before decrypting signing material. The CLI stores only the OWS alias / signer address plus non-secret defaults and local budget/cooldown/history ledgers. For autonomous agent runs, --yes --approval-id must refer to the human-approved policy or plan that allows the agent to send this exact tip inside the local cap.

If boon is not installed on PATH, run from a checked-out repo with:

node cli/dist/index.js doctor

Use dry-run for the operator-facing preview:

boon tip --dry-run <canonical-handle> <amount-usdc> "<note>"

Only after the relevant approval policy is satisfied, use the live command:

boon tip <canonical-handle> <amount-usdc> "<note>"

The CLI is expected to:

report OWS agent-wallet funding and contract readiness with boon doctor
canonicalize the handle before hashing
enforce the local cap, per-tip cap, note length, and cooldown
support boon tip --dry-run / --json without moving funds
run every boon tip through the connected OWS agent wallet; use the web /send page for explicit human browser-wallet sends
refuse to send if no OWS wallet is connected, if the OWS balance is below the requested amount + gas headroom, or if the per-tip / period-cap / cooldown guardrails would be violated
execute OWS agent sends through the Boon OWS adapter and OWS API-token policies, not by handling raw OWS private keys
call Boon.tip(handleHash, displayHandle, amount, note)
append to ~/.boon/history.jsonl
print the transaction hash

After execution, return:

Sent:
- github:alice — 10 USDC — <base tx link>
  note: "pr:owner/repo#42 — caught race in bundler"

If a transaction fails, surface the exact failure and stop. Do not retry with a larger allowance, different contract, different chain, or guessed handle.

Adapter execution

If an external wallet/signing adapter is used instead of the CLI, keep it behind an explicit via <adapter> operator choice and apply the same safety gates:

read-only credentials are fine for proposal/read paths
write credentials require explicit operator approval
no unrestricted approvals for this skill
amount must be at or below the approved spend/session cap
show calldata summary before submit
simulate/dry-run when available
never store adapter API keys or secrets in the repo

Claim-help mode

Use this mode for recipients or senders asking how claims work.

Explain in plain language:

A boon is escrowed to a canonical social handle until linked.
Recipient opens the claim UI, completes OAuth for that provider, connects a wallet, and receives a signed Link voucher.
link(handleHash, canonicalHandle, recipient, deadline, signature) binds the handle once.
claim(handleHash) sweeps escrowed USDC to the linked wallet.
Future boons to that handle push directly to the linked wallet.

Safety notes:

Boon cannot move funds from the recipient’s wallet.
The backend only attests OAuth ownership through a short-lived Link voucher.
The provider is bound explicitly in the voucher via providerHash.
Normal public linking is one-shot. The live contract has relink() for operator-assisted recovery with a fresh Boon-signed proof; it affects only future pushes and does not move already-pushed funds.

Optional intelligence endpoints

It is acceptable for a future agent surface to use a small paid endpoint for proposal scoring, artifact resolution, or risk checks, but never for claiming or receiving funds.

Good paid-helper boundaries:

propose-weekly: rank candidates from a provided activity corpus
resolve-artifact: normalize PR/post/task/tx references into note prefixes
risk-check: summarize a prepared transaction before operator approval

Rules for any paid helper:

disclose max cost before calling
do not fabricate if it fails
retry at most once on transient errors
render structured output with confidence and evidence
keep the final send path governed by the execution checklist above

Anti-Patterns

Refuse or reshape requests that ask to:

send without explicit operator approval
tip from an unverified/ambiguous handle
use private keys supplied in chat
use a non-Base chain or non-USDC asset in v1
hide the tip, note, or public receipt
charge a recipient to claim
turn Boon into bounty escrow, payroll, or autonomous reward distribution

Suggested reshape:

I can draft a boon proposal with candidates, evidence, amounts, and notes. Nothing will be sent until you approve exact rows.

Output Format

Use the mode-specific output shapes above and keep these invariants:

Proposal mode: Boons proposal for <period> with numbered rows containing handle, amount, note, why, evidence, and status: ready|needs_check, followed by total budget usage and the reminder that no funds move until approval.
Execution preview: Prepared Boon with handle, amount, note, chain, contract, call shape, and an explicit approval question.
Execution result: Sent: rows with canonical handle, amount, Base tx link, and note. On failure, return the exact error and stop.
Claim-help: plain-language steps for OAuth, wallet link, voucher, claim, and future direct delivery, plus safety notes that Boon cannot move recipient funds.
Refusal/reshape: explain the unsafe request briefly and offer a safe proposal-only alternative.

Examples

One-off approved tip

User: boon github:alice 5 USDC for PR #42 review

Agent:

Prepared Boon:
- handle: github:alice
- amount: 5 USDC
- note: "pr:owner/repo#42 — review"
- chain: Base 8453
- contract: <Boon contract>
- call: tip(handleHash, displayHandle, amount, note)
Approve send? No funds move until you confirm.

Preflight:

boon tip --dry-run github:alice 5 "pr:owner/repo#42 — review"

On approval:

boon tip github:alice 5 "pr:owner/repo#42 — review"

Weekly review

User: run weekly boons

Agent:

Gather the last 7 days of available collaboration signal.
Exclude cooldown hits.
Propose 1-3 rows with evidence and notes.
Wait for approval or edits.
Preflight approved rows with boon tip --dry-run.
Execute approved rows with boon tip.

Claim explanation

User: I got a boon, how do I claim?

Agent:

Open the claim page, verify the same provider handle that received the boon,
connect a wallet, and submit the link/claim transactions. Existing escrow moves
to your wallet, and future boons to that handle push directly there.

x402 paid graph

Boon agent skill file

Boon agent skill file

Skill metadata

Skill body

Boon — retroactive gratitude settlement

Contract

Critical rules

Mode selector

Data model and conventions

Canonical identity

Artifact/source note convention

Proposal mode

1. Gather signal

2. Score candidates

3. Render proposals

Execution mode

Preflight checklist

CLI execution

Adapter execution

Claim-help mode

Optional intelligence endpoints

Anti-Patterns

Output Format

Examples

One-off approved tip

Weekly review

Claim explanation

Get started

Concepts

Guides

API reference

Resources