Tokenomics Design

Tokenomics Design

Architect-level skill for token economic design and review. Focuses on what to build, why, and how it fails -- not on implementation code (route to solidity-security and web3-testing for that). The body is intentionally thin; depth lives in references/. Open only the file you need.

Companion skills (route to these first)

This skill is the economic-design layer. Defer to companion skills for adjacent domains:

| Domain | Use skill | |--------|-----------| | Public copy about token, staking, governance, fees | legalizer | | Whitepaper / litepaper authoring | whitepapers | | Cross-chain, custody, governance contract architecture | ultimate-web3 | | Solidity vulnerability classes and secure patterns (vesting wallets, governor, timelocks) | solidity-security | | Test design for vesting, emissions, governance (fuzz, invariants, fork) | web3-testing |

If the user asks for how to write the contract, route to solidity-security. If the user asks for how to publish or describe a token, route to legalizer. Use this skill for what the mechanism should be, what numbers it should use, and how it can fail economically.

Token economy rules for the agent

1. Read at most 2 reference files per turn. Choose by the routing table below.
2. Never improvise legal framing or marketing copy. Token-related public prose must pass legalizer.
3. Do not paste back numbers or schedules the user already provided. Critique or extend them.
4. Prefer tables, schedules, and equations over prose.
5. Use WebSearch for current unlock-schedule benchmarks, FDV/MCap norms by sector, and recent token launches. Norms change cycle-to-cycle.
6. When the user asks "is this tokenomics good?", run the Audit workflow below before commenting.

Routing table

| User intent or keyword | Open file | |------------------------|-----------| | Allocation tables, vesting, cliffs, TGE, ve-token, POL, dual-token, bonding curve, halvings, real yield, points-to-token, RPGF, gauge weights | references/patterns.md | | "Is this safe?", footguns, FDV-vs-float, emission death spiral, cliff dump, governance attack, airdrop dump, velocity, whale concentration, oracle manipulation, forced utility | references/sharp_edges.md | | Numerical review, "does this add up?", allocation sums, cliff durations, TGE %, supply caps, governance safeguards, distribution metrics | references/validations.md |

Golden rules (non-negotiable)

1. Utility before incentive. If the token has no functional role beyond capturing future value, it is a security narrative dressed as a token. Define what the token does in the running protocol before designing emissions.
2. Allocations sum to 100% and every wallet vests. Any insider allocation (team, investors, advisors, foundation employees) must have a cliff and a linear or stepped vesting schedule. No exceptions.
3. Emissions are a budget, not a feature. Every emitted token must have a buyer-of-last-resort thesis (protocol revenue, organic demand, lock-up sinks). Without it, the token is selling itself.
4. FDV / float ratio drives launch dynamics. A high-FDV / low-float launch concentrates dump risk at every unlock cliff. Model the unlock waterfall before announcing the cap table.
5. Governance is an attack surface. Snapshot voting, timelocks, quorum minima, and an emergency multisig are required from day one. Pure on-chain Governor with no timelock is a vulnerability.
6. Distribution > narrative. A token concentrated in 10% of circulating supply.

Phase 6: Compliance and disclosure

• Run all public-facing strings through legalizer.
• Publish vesting schedule and unlock waterfall before TGE.
• Cross-link audit reports for vesting and governance contracts.

Gate: zero legalizer hard-block phrases in any external document.

### Audit workflow (existing tokenomics)

Use this when reviewing a published or proposed token model.

1. Open references/validations.md and run every check against the user's spec.

For each failed check, cite the rule and quote the offending line.

1. Open references/sharp_edges.md and match the model against each failure mode.

For each match, name the failure ID and describe the symptom in this specific design.

1. Compute the unlock waterfall:

• For each insider cohort: cliff date, total tokens, unlock pace.
• For each month after TGE: tokens unlocked, % of then-circulating, % of total supply.
• Flag any month where unlock > 10% of circulating supply.

1. Compute the emission sustainability ratio:

weeklyemissionvalue = weeklytokenemissions * currentprice weeklybuypressure = protocolrevenue + organicdemandestimate + newcapitalinflow sustainabilityratio = weeklybuypressure / weeklyemission_value Flag if ratio = 6 months) and a vesting schedule.

• [ ] TGE unlock for insiders is 0% (or documented exception with justification).
• [ ] Token has at least one functional utility in the running protocol; design survives "remove the token" thought experiment.
• [ ] Emission schedule is bounded (cap, halving, or terminal date).
• [ ] Sustainability ratio modeled for year 1 and year 2; thresholds defined.
• [ ] Unlock waterfall published; no single month exceeds 10% of circulating supply.
• [ ] Governance has timelock (>= 48h), quorum, proposal threshold, emergency multisig.
• [ ] Value accrual mechanism specified (real yield, treasury growth, lockup demand) -- not "buyback hopes".
• [ ] Distribution targets named (top-10, top-100, Gini) and tracked post-launch.
• [ ] All public-facing copy passes legalizer hard-block list.
• [ ] Vesting and governance contracts referenced to audited implementations (e.g. OpenZeppelin v5 VestingWallet, Governor, TimelockController) or carry their own audit.
• [ ] Whitepaper / litepaper section on tokenomics matches this spec exactly.

Do not

• Do not propose mechanisms that exist purely to create token demand (forced utility, artificial sinks).
• Do not quote APYs above ~30% as sustainable; emissions-funded yields collapse.
• Do not recommend "buyback and burn" as a primary value-accrual story; it is often a red flag for missing utility.
• Do not design 1-token-1-vote governance for any treasury > $1M.
• Do not ship without a published unlock waterfall.
• Do not write public-facing copy from inside this skill; route to legalizer.
• Do not invent percentages or vesting numbers when the user provided real ones; critique the user's numbers instead.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kaynetik
• Source: kaynetik/skills
• License: MIT

Install and usage instructions live in the source repository linked above.