Bracketsbot Skill

Generate, validate, and submit BracketsBot NCAA tournament brackets.

Security Scan

The skill appears to implement the described bracket-generation and unsigned transaction preparation functionality, but there are mismatches between what it declares (instruction-only, no runtime requirements) and the actual bundled code/usage (a Node CLI with dependencies and file-write behavior), so review and cautious deployment are advised.

Purpose & Capability

Name/description match the included code: the repo contains a CLI, match/tournament data, policy examples, and scripts to prepare unsigned on-chain transactions. However, the registry metadata claims 'No install spec' and 'no required binaries/env', while the packaged tool is a Node CLI (package.json -> bin: './scripts/cli.mjs') and expects a Node runtime and optional tools (pnpm, jq, bankr) for some flows. That mismatch (no declared runtime requirements vs. a real CLI) is inconsistent.

Instruction Scope

SKILL.md instructions stay on-purpose: they document generating picks, stepping through matchups, running policies, validating, producing a share link, and preparing unsigned transaction payloads. The skill explicitly instructs agents to ask the user before signing/submitting on-chain and to prefer share-links for human browser submission. It does write/read local state files (out/model-walk-picks.json by default) and references env vars/options for file paths (PICKS_FILE, TOURNAMENT_FILE, etc.), which is expected for a CLI that persists walk state.

Install Mechanism

No install spec is provided in the registry metadata, but the package includes a package.json with dependencies (incur, viem) and a Node CLI. Running the CLI as recommended (pnpm run cli ...) requires Node and package installation. The absence of a declared install/install instructions (and no required binaries listed) is a practical inconsistency that could cause an agent to attempt to run commands that don't exist in its environment. Dependency 'viem' indicates EVM transaction construction capability (expected for prepare-submit-tx) but also increases runtime footprint.

Credentials

The skill declares no required environment variables or credentials, which aligns with its stated policy of preparing unsigned transactions only. Example flows reference external wallet tooling (Bankr CLI) and warn to verify chainId/to/value before signing, but the skill itself does not request secrets. A reviewer should confirm prepare-submit-transaction implementation to see the recipient address and chainId (the code may embed or compute 'to' and 'chainId' values).

Persistence & Privilege

The skill is not 'always:true' and does not request elevated platform privileges. Its CLI writes and reads local state files (out/model-walk-picks.json) to support stepwise workflows; this is expected behavior for the described use-case. There is no indication it modifies other skills or system-wide agent settings.

What to consider before installing

This skill largely does what it says (generate/validate brackets and prepare unsigned on-chain payloads), but there are a few practical mismatches you should consider before installing or letting an agent run it automatically: - Runtime requirements: The package contains a Node CLI (package.json) and npm dependencies (viem, incur). Ensure your agent/runtime has Node and the dependencies installed (pnpm/npm) before expecting the CLI to run; the registry metadata did not declare these requirements. If your agent runs commands automatically, it may attempt to call a binary that isn't present. - Unsigned txs vs signing: The skill prepares unsigned transaction payloads (chainId, to, data, value). It does not need your private keys, and SKILL.md repeatedly instructs to ask the user before signing/submitting. Never sign or broadcast a prepared tx without manually verifying chainId, destination address ('to'), and value. Review scripts/prepare-submit-transaction.mjs to confirm the 'to' address and contract it targets. - Local file writes: The tool persists walk state in out/model-walk-picks.json (default). If you run this in shared environments, be aware of file-write behavior and concurrency guidance in WALK_STATE.md. - External wallet examples: Example flows show using Bankr or other CLI wallets. Those require separate wallet tooling and credentials—this skill doesn't request them but will produce payloads that such tools can sign. Only proceed with signing if you trust the payload and the contract. - Review the code before running: Because the package bundles scripts that can construct transactions, quickly scan scripts/prepare-submit-transaction.mjs and related files to confirm they don't point to unexpected network endpoints or hard-coded recipient addresses you don't want to interact with. If you want to proceed safely: run the CLI locally in a contained environment, inspect the generated unsigned tx payload, and use a testnet/dry-run to verify behavior before using real funds or giving the agent autonomous execution rights.

This skill helps agents run the bracketsbot CLI safely and consistently.

When To Use

Use this skill when user asks to:

• generate tournament bracket picks with AI/model logic
• step through matchups and decide winners incrementally
• run a custom policy function over the bracket
• prepare (not directly sign) transaction payloads for onchain submission
• generate a shareable frontend URL so a human can review and submit a model-picked bracket (in-progress or full)

First-run onboarding (do this before filling a bracket)

When: The user has just asked to generate a bracket, fill out picks, or do something with the BracketsBot bracket—and you have not already agreed on how to proceed in this conversation.

Do not run walk-next, walk-run-policy, or semantic-run until you have done onboarding and the user has answered (or clearly chosen a path).

1. Relay this (or similar) text first:

“I can help you build a March Madness bracket for BracketsBot. We’ll pick winners for all 63 games, then you can submit it on-chain. Before I start, I need a couple of choices from you.”

2. Ask these questions (one at a time or together):

• How do you want to pick the games?

  • “Together: We chat about every game step by step. I’ll follow simple rules, learn your approach, and make suggestions as we go.
  • Instructed: You give me a single general instruction for your bracket. I’ll check each matchup on my own and pick winners based on your rules.
  • Coded: We write a complex model using team statistics. At each matchup I’ll run our code that weighs stats and other heuristics. Which do you prefer?”

• How do you think you’ll want to submit when we’re done?

  • “Browser link: I’ll give you a link; you open it and submit with your browser wallet (e.g. MetaMask) on the BracketsBot site—no extra wallet tools needed.
  • Wallet/CLI: You’ll use something like Bankr or another signer; I’ll prepare the transaction and you sign from there. No need to decide now; I’ll ask again when the bracket is complete. Any preference for now?”

3. After they answer, proceed with the workflow that matches their choice: Together → A (stepwise walk), Instructed → B (semantic-run with their rule), Coded → C (walk-run-policy with a stats module). If they didn’t choose a submission path yet, that’s fine; ask again when the bracket is complete (see below).

Key Principles

1. Canonical winner ID is seed (1..64) for all predictions/submission.
2. Two distinct tasks: (1) filling out the bracket (picks), and (2) submission (getting it on-chain). Do first-run onboarding before filling (see above). When the bracket is complete (63 picks), prompt the user for how they want to submit—don’t assume.
3. Prefer validation before submission (validate command).
4. Use stepwise commands for chat-agent loops, policy command for developer code loops.
5. For chat agents, prefer natural-language policy execution (do not write JS unless user asks).

When the bracket is complete (63 picks): ask how to submit

After generating or walking a full bracket, prompt the user for their preferred submission path:

1. Suggest the share link first: Run share-link (or share-link --predictions-file ./out/model-bracket-output.json if the bracket came from Instructed or Coded and was written to that file). Give them the shareUrl and say they can open it in a browser and submit with their browser wallet (MetaMask, Coinbase Wallet, etc.) on the BracketsBot site—no CLI or external wallet needed.
2. Otherwise ask: “Do you want to use a wallet skill or CLI (e.g. Bankr, prepare-submit-tx) to sign and submit from here?” If yes, run prepare-submit-tx and hand the payload to their chosen tool.

Example prompt you can use: “Your bracket is complete. How do you want to submit? I can give you a link to open in your browser and submit with your browser wallet, or we can prepare a transaction for you to sign with Bankr / another wallet tool—which do you prefer?”

Commands

Prefer direct CLI commands:

bracketsbot validate --json
bracketsbot prepare-submit-tx --json

Stepwise / instructed / share:

bracketsbot walk-next --json
bracketsbot walk-apply --winner-seed <seed> --json
bracketsbot walk-run-policy --policy-module <path> --json
bracketsbot semantic-run --policy "<policy text>" --predictions-file <file> --json
bracketsbot share-link --json

share-link: Defaults to in-progress walk state (./out/model-walk-picks.json). After walk-apply (Together), run share-link with no arguments to get a link for the current picks. For a full bracket from Instructed or Coded (e.g. written to ./out/model-bracket-output.json), run share-link --predictions-file ./out/model-bracket-output.json. The frontend shows only the picks in the link (no auto-fill).

If bracketsbot is not on PATH in local development, fallback to:

pnpm run cli <command> ...

Recommended Workflows

A) Together (stepwise chat)

User chose Together in onboarding: chat each game, learn their approach.

1. call walk-next
2. apply the user's rules / suggestions to teamA vs teamB; call walk-apply --winner-seed ...
3. repeat until done: true
4. Then ask how they want to submit (share link vs wallet tool)

Example natural-language policy prompts:

• "Pick based on mascot battle outcomes."
• "Always favor better defense unless the underdog has higher recent momentum."
• "Prioritize upset potential in round 1, then revert to strongest teams."

B) Instructed (one general rule)

User chose Instructed in onboarding: one general instruction; agent applies it to every matchup.

1. Agent reasons through all 63 matchups using the user's rule; produces 63 winner seeds.
2. Write picks to a JSON file.
3. Run semantic-run --policy "<user's instruction>" --predictions-file <file>.
4. Then ask how they want to submit (share link vs wallet tool)

C) Coded (stats/heuristic module)

User chose Coded in onboarding: we write a model using team stats; code runs at each matchup.

1. create module exporting chooseWinner (weighs stats, etc.)
2. call walk-run-policy --policy-module ...
3. call validate
4. Then ask how they want to submit (share link vs wallet tool)

D) Share link (frontend review / submission)

When the user wants to open the bracket in the frontend to review or submit:

1. In-progress (Together, stepwise walk): run share-link with no arguments. It reads the same file walk-apply writes. Give the user the shareUrl from the JSON output.
2. Full bracket (Instructed or Coded, output in a file): run share-link --predictions-file ./out/model-bracket-output.json (or the path where picks were written). Give the user the shareUrl.

The frontend shows only the picks in the URL (no auto-fill of remaining games). If the user doesn’t have wallet tools set up (e.g. no Bankr or CLI signer), the share link is the submission path: they open it in a browser and submit using their browser-based wallet (e.g. MetaMask, Coinbase Wallet) from the BracketsBot site.

Wallet Submission

Two paths; the agent should ask when the bracket is complete (see “When the bracket is complete” above):

• Browser: Run share-link, give the user the URL; they open it and submit on the BracketsBot frontend with their browser wallet. No CLI or external wallet needed.
• Wallet tools: Use prepare-submit-tx, then submit via bankr submit json (if Bankr is installed) or another EVM signer (see reference/WALLET_INTEGRATIONS.md).

Avoid requiring private-key custody in this package unless user explicitly requests local submit flow.

Important Files

• reference/WALK_STATE.md
• reference/WALLET_INTEGRATIONS.md