What if the vault is not in the list?

Re-check the address first; if missing, document the reason in the note.

How long should the note be?

Long enough to explain the risk or anomaly in plain language.

When should I set BAD_FLAGS?

Only when evidence is clear; avoid labeling without proof.

Skill BreakdownDeFi Vault OpsNo AI Required

Add Vault Note: Structured annotations for DeFi vaults

Turn the add-vault-note skill into an execution-ready workflow with input templates, VaultFlag decisions, flag.py edits, and PR guardrails.

Here "vault" refers to DeFi vault data, not password managers or note-taking apps.

View Skill Source Open Vault List

Required Inputs

Have these ready before you start.

Vault smart contract address (lowercase in flag.py)

Human-readable note explaining the reason or risk

Optional VaultFlag (set to None if unspecified)

Outputs

The end result is a traceable PR.

New VAULT_FLAGS_AND_NOTES entry

Message constant + flag pairing

notes-prefixed PR (no changelog)

Input Template

Copy-paste and fill this template.

Vault address: 0x...
Message: "Reason / risk note"
Flag: None | VaultFlag.illiquid | VaultFlag.broken | ...

Address must start with 0x and remain lowercase.

Workflow

Four steps to finish add-vault-note

From data lookup to PR naming, every step is explicit.

Resolve vault name

Find the vault name via official lists instead of guessing.

Use top_vaults_by_chain.json (search in file, do not open) or the vaults list page. check-vault-onchain.py is a fallback.

Search top_vaults_by_chain.json by address → extract name (do not open the full JSON).

Edit flag.py

Add a message constant and a VAULT_FLAGS_AND_NOTES entry (lowercase address).

If no flag was specified, set it to None.

# eth_defi/vault/flag.py
NEW_VAULT_NOTE = "Reason for flag"

VAULT_FLAGS_AND_NOTES = {
  "0x...": (VaultFlag.illiquid, NEW_VAULT_NOTE),  # Vault Name
}

Format & validate

Run ruff so the change matches repo formatting.

Limit formatting to the target file for clarity.

ruff format eth_defi/vault/flag.py

Open PR

Prefix the PR title with notes and skip changelog.

Helps reviewers spot data-note updates quickly.

Prefix PR title with "notes" (not feat). No changelog required.

VaultFlag Matrix

Choose the right flag faster

BAD_FLAGS imply elevated risk and require evidence.

Category	Flags	Usage note
Operational	deposit, redeem, paused, trading, idle	Describes whether funds can move and the trading state.
Risk/Anomaly	illiquid, broken, malicious, abnormal_tvl, abnormal_price_on_low_tvl	High-risk warnings aligned with BAD_FLAGS.
Structure/Source	proprietary_trading, wrapped_asset, unofficial, subvault	Explains vault structure or listing issues.

Risk note

BAD_FLAGS like illiquid/broken/malicious affect user decisions; include verifiable evidence.

Vault Summary JSON

Fast path to name, address, and chain

Field meanings follow Trading Strategy docs for source alignment.

Field	Meaning	Why it matters
name	Human-readable vault name (may include chain)	Use as the note comment to avoid name confusion.
address	Vault contract address	Match the input address before writing the note.
chain / chain_id	Chain name and numeric chain ID	Deduplicate same-name vaults across chains.
protocol	Protocol operating the vault	Adds context for risk and note rationale.
risk	Technical risk classification	Signals whether BAD_FLAGS are justified.
denomination	Denomination asset (e.g., USDC)	Confirm the vault type and unit of account.

Usage note

top_vaults_by_chain.json is large; search within it instead of opening the full file.

Self-check list

Must pass before submitting.

Address is lowercased and not already present in VAULT_FLAGS_AND_NOTES.

Message constant is created and referenced in the dictionary.

Flag selection has evidence; set to None when unspecified.

ruff formatting completed for the target file.

PR title starts with notes and no changelog entry was added.

Scoring guide

6 points total. Submit at 6+.

0-3: Incomplete, gather evidence.

4-5: Submit with extra review.

6-7: Ready to submit.

Self-Test

5 questions to validate readiness

Each is 1-2 points. Answer before submitting.

How do you confirm the vault name?

Score: 2

Search the official vault list JSON or the vaults page by address.

Why must the address be lowercased?

Score: 1

flag.py matches against lowercased keys; mismatch breaks lookup.

What to write if no flag is specified?

Score: 1

Set the flag to None and keep the message constant.

Any PR naming rules?

Score: 1

Prefix the title with notes, not feat.

Which formatting step is required?

Score: 1

Run ruff format on the target file.

Resources

All authoritative sources in one place

Use these references to verify every step.

GitHub Repo

web3-ethereum-defi repository home

Open link

Skill Source

Original add-vault-note workflow definition

Open link

Vault Data Docs

Vault summary JSON format and fields

Open link

Vault List

Official vault list and search interface

Open link

Vault Summary JSON

top_vaults_by_chain.json (search within the file)

Open link

Source Kit

Source, clone, and license in one view

Meets open-source compliance and reduces context switching.

Skill source	https://github.com/tradingstrategy-ai/web3-ethereum-defi/blob/master/.claude/skills/add-vault-note/SKILL.md
Clone command	`git clone https://github.com/tradingstrategy-ai/web3-ethereum-defi.git`
License	MIT (per README)