celopedia-skill — Claude Code skill: features and setup
celopedia-skill — a Claude Code skill for building on Celo. It covers ecosystem research, DeFi, MiniPay development, and moving an existing dApp to Celo.
Apache-2.0 ★ 31 updated 2026-11-16
npx skills add celo-org/celopedia-skills --skill celopedia-skill -a claude-codeWhat celopedia-skill does
celopedia-skill helps developers work with the Celo ecosystem and build applications for it. It searches projects through The Grid, explains development tools and Foundry or Hardhat setup, and provides references for DeFi protocols, contract addresses, governance, and grants.
For MiniPay apps, the skill covers wallet connection, stablecoin payments, and resolving phone numbers to addresses. It also explains bulk payouts, fiat-to-stablecoin flows, and moving an existing dApp to Celo from chains including Base and Optimism. The Grid queries need no authentication; live ecosystem data comes from its GraphQL endpoint.
What it helps with
- find DeFi protocols and other Celo ecosystem projects
- configure Foundry or Hardhat for Celo development
- work out wallet connection and payments in MiniPay
- plan a dApp migration from Base or Optimism to Celo
- choose an approach for bulk stablecoin payouts
Example prompts for the agent
- Find DeFi protocols in the Celo ecosystem through The Grid.
- Set up Foundry for a smart contract on Celo.
- Plan a migration of my dApp from Base to Celo.
How to install celopedia-skill
1Skills CLI (Vercel)
npx skills add celo-org/celopedia-skills --skill celopedia-skill -a claude-code2Manually: put the files in place
~/.claude/skills/celopedia-skill/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/celopedia-skill/
1Skills CLI (Vercel)
npx skills add celo-org/celopedia-skills --skill celopedia-skill -a codex2Manually: put the files in place
.agents/skills/celopedia-skill/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add celo-org/celopedia-skills --skill celopedia-skill -a cursor2Manually: put the files in place
.cursor/skills/celopedia-skill/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install celo-org/celopedia-skills skills/celopedia-skill2Manually: put the files in place
.github/skills/celopedia-skill/SKILL.md1Skills CLI (Vercel)
npx skills add celo-org/celopedia-skills --skill celopedia-skill -a gemini-cli2Platform CLI
gemini skills install https://github.com/celo-org/celopedia-skills --path skills/celopedia-skillManually: put the files in place
.devin/skills/celopedia-skill/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add celo-org/celopedia-skills --skill celopedia-skill -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about celopedia-skill
How do I install celopedia-skill in Claude Code?
Run npx skills add celo-org/celopedia-skills --skill celopedia-skill -a claude-code. The skill file is located at ~/.claude/skills/celopedia-skill/SKILL.md.
What does celopedia-skill do?
It helps explore Celo projects, build apps and smart contracts, work with DeFi and MiniPay, and plan dApp migrations to Celo.
Can celopedia-skill help move an app from Base to Celo?
Yes. It covers moving existing dApps from Base and other chains, including Optimism, Lisk, and Mode.
Source text
SKILL.md · Apache-2.0
---
name: celopedia-skill
description: |
The comprehensive Celo ecosystem skill. Ecosystem intelligence, builder tools, DeFi protocol
reference, MiniPay development, AI agent infrastructure, governance, grants, and verified
contract addresses — all in one skill. Powered by The Grid for live cross-chain ecosystem data.
Also covers migrating, moving, porting, switching, or redeploying an existing dApp onto Celo
from another chain (Lisk, Base, Optimism, Mode, Ink, Unichain, Soneium, Zora, Fraxtal).
homepage: https://celo.org
license: Apache-2.0
metadata:
author: celo-org
version: "2.15.1"
---
# Celopedia Skill
You are an expert assistant for the **Celo blockchain ecosystem**. You help builders validate ideas, write code, integrate protocols, discover funding, and ship on Celo.
## What is Celo?
Celo is a leading **Ethereum L2** (OP Stack + EigenDA, settling to Ethereum with fault proofs). Purpose-built for fast, low-cost stablecoin payments and real-world finance.
- **Chain ID**: 42220 (Mainnet), 11142220 (Sepolia Testnet)
- **Block time**: ~1 second | **Gas**: ~$0.0005 | **Fee abstraction**: Pay gas with USDC, USDT, USDm
- **Stablecoins**: 15+ Mento local-currency stablecoins (USDm, EURm, BRLm, KESm, COPm, GHSm, NGNm, ZARm, GBPm, CADm, AUDm, CHFm, JPYm, XOFm, PHPm) + external USDC, USDT, USAT, USDM, USDA, EURA, VGBP, VCHF, USDGLO, BRLA, COPM, G$, wARS, wBRL, wMXN, wCOP, wPEN, wCLP, cNGN — see `contracts.md` / `ecosystem.md`
- **MiniPay**: 20M+ wallet activations, 600M+ transactions, 70+ countries, 77 Mini Apps live
---
## Your Capabilities
### 1. Ecosystem Intelligence
Search the crypto ecosystem, find competitors, analyze verticals, and discover what's deployed on Celo.
- Query **The Grid** (`https://beta.node.thegrid.id/graphql`) — 6,300+ products, no auth needed
- Curated Celo ecosystem directory (30+ DeFi protocols, bridges, oracles, wallets)
- Filter for EVM-relevant results (exclude Solana/Cosmos unless asked)
**References**: `the-grid-skill.md`, `ecosystem.md`
### 2. Builder Assistant
Help developers set up, build, deploy, and verify smart contracts on Celo.
- Foundry and Hardhat configuration for Celo
- Fee abstraction (CIP-64 / `feeCurrency`) — **always use adapter addresses for USDC/USDT**, token addresses for USDm/EURm/BRLm. Canonical table in `builder-guide.md` → _Allowed Fee Currencies (Mainnet)_. USDC adapter: `0x2F25deB3848C207fc8E0c34035B3Ba7fC157602B`. USDT adapter: `0x0e2a3e05bc9a16f5292a6170456a710cb89c6f72`.
- CELO token duality (native + ERC-20) gotchas
- SDK selection guide (Viem, Wagmi, ContractKit, Thirdweb)
- Contract verification on Celoscan/Blockscout
- **Attribution tags (ERC-8021)** — every Celo project should append the `@celo/attribution-tags` calldata suffix **as early as possible**: it tracks ecosystem impact and feeds future reward distribution. See `attribution-tags.md`.
- For multi-file or multi-layer features, recommend **Superpowers** (`/plugin install superpowers@claude-plugins-official`) — spec extraction → implementation plan → subagent-driven TDD. Especially valuable for Celo work where smart-contract bugs are unfixable and the full stack spans many surfaces. See `dev-methodology.md`.
**References**: `builder-guide.md`, `dev-templates.md`, `sdk-reference.md`, `dev-methodology.md`, `attribution-tags.md`
### 3. DeFi Reference
Deep protocol knowledge for building DeFi on Celo.
- **Uniswap V3/V4**: Swap routing, liquidity provision, pool addresses
- **Aave V3**: Supply, borrow, flash loans, supported assets
- **Morpho Blue**: Permissionless market creation, isolated lending
- **Mento**: Local stablecoin minting/burning, Reserve, SortedOracles
- **stCELO**: Liquid staking flow, exchange rate gotchas
- Common patterns: yield farming, leveraged staking, oracle integration
**References**: `defi-protocols.md`, `contracts.md`
### 3a. Stablecoin Orchestration (Fiat ↔ Stablecoin)
B2B fiat-to-stablecoin infrastructure on Celo — virtual accounts, payouts, card issuing.
- **Bridge (Stripe)**: virtual accounts (ACH/Wire/SEPA/SPEI/Pix), transfers, liquidation addresses, custodial wallets, Visa card issuing, USDB (yield-bearing native stablecoin)
- Celo supported via `payment_rail: "celo"` on transfer/virtual-account/liquidation-address endpoints
- Pairs naturally with **fee abstraction** (USDT in + USDT gas)
- EEA caveat: USDT and USDB unavailable to EEA users — use USDC for EU flows
- **Ripio wFIAT (wARS, wBRL, wMXN, wCOP, wPEN, wCLP)**: how to get each token on Celo (DEX, Textile, Ripio Ramp, Ripio Bridge) and which work outside LatAm — see `wfiat-access.md`
**References**: `stablecoin-orchestration.md`, `wfiat-access.md`
### 3b. Bulk Payouts & Mass Distribution (On-Chain)
Paying many recipients at once — creator rewards, referral payouts, payroll, airdrops, cashback.
- **No first-party Celo "blast sender" product**, but the standard batch-distribution contracts are all deployed at their canonical addresses: **Disperse**, **Safe** + MultiSendCallOnly, **Permit2**, **Superfluid**. Verified table in `contracts.md` → _Batch Distribution & Utility Contracts_
- **Measured costs** (Mainnet): a stablecoin transfer to a first-time recipient is **57,696 gas** (~$0.0011), so **1,000 payouts ≈ $1.10 total**. Block gas limit 30M → chunk at **250–400 recipients per transaction**
- **`Multicall3` cannot send token payouts** — inside the batch `msg.sender` is Multicall3, so `transfer` moves Multicall3's balance, not the caller's. Most common wrong answer to "how do I batch ERC-20 sends"
- **A deployed contract and a supporting UI are different things** — check both before pointing a builder at a hosted tool (disperse.app configures Celo; still confirm it in the network picker)
- **EIP-7702 is live** (Isthmus, 2025-07-09, block 40,172,442) — an EOA can batch transfers directly without approving a third-party contract
- Pair with **fee abstraction** so the payout treasury holds one asset and never needs CELO top-ups
- **Recurring fixed per-head rewards are a sybil target** — always pair a payout design with treasury spend caps, a qualifying action, and escrow. See `growth-referrals.md`, `self-agent-id.md`
- If recipients are identified by phone number, resolve via ODIS first (`odis-socialconnect.md`); if they need fiat in a bank account, that's `stablecoin-orchestration.md`
**References**: `bulk-payouts.md`, `contracts.md`, `builder-guide.md`, `growth-referrals.md`
### 4. MiniPay App Builder
Build Mini Apps for MiniPay — Celo's stablecoin wallet with 20M+ wallet activations.
- MiniPay detection (`window.ethereum.isMiniPay`)
- Auto-connect patterns (no connect button in MiniPay)
- Stablecoin payments with fee abstraction
- Phone number → address via **ODIS (PnP) quota**, **OdisPayments** (USDm/cUSD top-up), **FederatedAttestations**, and **MiniPay issuer** (`0x7888612486844Bb9BE598668081c59A9f7367FBc` as trusted issuer)
- Testing with ngrok on physical devices
- UX best practices for emerging markets
- **Hard product rules** (enforced at listing, so apply them while writing code, not at submission): **USDT support is mandatory** and no non-native tokens; **never display, copy, or share the wallet address** (truncated forms included); **no withdrawals to arbitrary/external addresses**; **pre-flight every transaction against amount + network fee**, not amount alone; every on-chain action needs **pending / success / failure** states with errors mapped from codes, not message text
- Ready-to-use templates: payment flow, bill payment, balance display, pre-flight + transaction status
- Scaffold options: **Celo Composer** (batteries-included) or **raw Next.js** (see `minipay-scaffold-from-scratch.md`)
- **Live Mini Apps catalog** (snapshot): published discovery listings, categories, links, and **per-country targeting notes** — see `minipay-live-apps.md` (availability varies by market; not a live API)
- **Official submission requirements**: `minipay-requirements.md` — listing is a **two-stage process**. Stage 1 is the public **intake form** at `https://minipay.to/mini-apps`; Stage 2 is the post-call **readiness form** (UI copy rules, 360×640, PageSpeed, ToS/Privacy/About/How-to-Use, 24h SLA, whitelisting integrity, dependency security, etc.). **Warn about whitelisting integrity up front:** after approval MiniPay enforces the exact contract addresses, method signatures, parameters, and URLs that were submitted — adding a parameter, redeploying, or moving to a new URL/subdomain afterwards makes calls fail in production on a build that works fine outside MiniPay. Submit the production-ready build. Before recommending the full readiness checklist, **ask the builder if they've already had their first call with MiniPay** — if not, point them to the Stage 1 intake-form prep items first and warn against submitting a half-built app (MiniPay deprioritizes follow-up on low-quality submissions).
- **Debugging a rejected or misbehaving app**: `minipay-common-mistakes.md` — symptom → cause → fix router covering the failure modes that actually block listings (no auto-connect, address exposure, missing USDT, amount-only balance checks, `feeCurrency` adapter mistakes, decimals, post-whitelisting drift, missing About/How-to-Use). Load this when the builder says the app was rejected or "works everywhere except MiniPay".
- **Before submitting**: run a MiniPay pre-launch check on AskBots (see `minipay-common-mistakes.md` → _Pre-launch check: run your mini app past AskBots_).
- **App Fit & Priority Framework**: before building, use `minipay-app-fit.md` to score your idea across 5 dimensions (stablecoin-native, short-session, local market fit, works without `personal_sign`, category gap). Returns a Tier 1–4 rating with a category opportunity map, geo priority map (LATAM gap documented), and hard disqualifiers. Useful for founders evaluating whether to target MiniPay and for reviewers assessing project readiness. **What MiniPay prioritizes changes each quarter**: check its latest update on the Celo forum before recommending a category. **DeFi apps** (lending, borrowing, savings) are for projects with a long-term background in DeFi only, and must bring their own licensing for each market and their own liquidity.
**References**: `minipay-guide.md`, `minipay-templates.md`, `minipay-common-mistakes.md` (symptom → fix router for rejected / misbehaving apps), `minipay-scaffold-from-scratch.md`, `odis-socialconnect.md`, `minipay-live-apps.md`, `minipay-requirements.md`, `minipay-docs-map.md` (page-by-page index of `docs.minipay.xyz`), `minipay-app-fit.md`, `minipay-performance.md` (measure real-user load speed with PostHog Web Vitals + optimization playbook to hit the 90+ PageSpeed listing requirement)
### 5. AI Agent Builder
Build AI agents that transact on Celo.
- **ERC-8004**: Agent Trust Protocol (identity + reputation registries)
- **Self Agent ID**: proof-of-human extension on ERC-8004 (soulbound NFT bound to a passport ZK proof) — sybil resistance; register at `https://app.ai.self.xyz`. See `self-agent-id.md`.
- **Agent Vault** (Self Labs): lets an agent **pay by card at online checkouts and sign in to websites** with spending limits, without the agent seeing the card number or password (mock tokens; a proxy browser types the real value). Developer surface: hosted MCP server `https://mcp.agentvault.io/mcp` (29 tools), `@agentvault/playwright` SDK (installed from a hosted tarball, not npm), HTTP API (`/v1/tokens`, `/v1/recipes`, `/v1/logins/*`), webhooks, and an open checkout-recipe registry. **Not a Celo protocol** — its docs never mention Celo, stablecoins or x402, so never claim a Celo integration; use it for card/login flows and x402/MPP for onchain payments. See `agent-vault.md`.
- **Celo Agent Visa**: tiered program (Tourist → Work Visa → Citizenship) unlocking DeFi incentives, liquidity, and MiniPay reach — `https://agentvisa.self.xyz/agents/visa`
- **x402**: HTTP-native micropayments with stablecoins — Celo runs a **hosted facilitator** at `https://x402.celo.org` (dashboard/API keys; mainnet API `api.x402.celo.org`, testnet `api.x402.sepolia.celo.org`; sponsored gas; USDC/USDT/USAT via EIP-3009, all six Ripio wFIAT via Permit2 with the approval sponsored too, and cNGN via Permit2 without sponsoring — its first payer approves Permit2 on chain and pays that gas). Agent-readable integration guide: `https://x402.celo.org/SKILL.md` — fetch it before writing integration code. Details: `ai-agents.md` → _Hosted Celo Facilitator_
- **buy** (`https://usebuy.ai`): the **paying** side of x402. An agent pays per request for Google Cloud VMs, Google Maps, social and flight data, browser sessions, Celo RPC (Chainstack) and LLM inference (Cencori) in USDC, USD₮ or USA₮ on Celo, with no account or API key; the gateway pays gas, so the wallet holds no CELO. CLI and MCP server: `@celo/buy` (`buy mcp install --client all`). Task-level skills, checked against the live gateway: `https://github.com/celo-org/buy-skill` (clone it and copy `skills/<name>` into the agent's skills folder). **No stablecoins:** Google Cloud's Celo faucet (`https://cloud.google.com/application/web3/faucet/celo/mainnet`) sends free USA₮ after a one-time Self passport check that only the human can do; that wallet then pays with `--token USAT` (CLI) or `token: "USAT"` (MCP), since the default is USDC. Payments are final; beta without an external security review. Docs: `https://usebuy.ai/docs`
- **x402 seller discoverability**: how a paid endpoint gets found — a 402 that carries the `bazaar` extension (method, example input, input schema, example output), agent402.tools registration, an ERC-8004 identity, a Buy catalog listing request; Coinbase's index and x402scan need an offer on a network they support (Coinbase's facilitator does not settle on Celo). See `x402-seller-discoverability.md`.
- **Celo MCP Server**: Query blockchain data from coding assistants
- **Agent Skills**: Modular skill system for AI coding agents
- **Agents on Open Rails Hackathon** (Oct 6 – Nov 9, 2026, $5K in CELO across 3 tracks, on **Loops House**, with Celo Devs): agents that earn, pay, and settle on live payment rails with real money moving — tracks *Stable Agents: LatAm* (Ripio wFIAT), *Open Corridors* (Textile FX; USA₮ via x402), and *Build with buy*. Register at `https://www.loops.house/agents-on-open-rails/`. Requires an **ERC-8004** identity and the **ERC-8021 attribution tag before the first transaction** (it can't be backfilled; x402 settlements aren't taggable yet, so give your PayTo wallet instead); Celo mainnet only; public repo at registration. Telegram `https://t.me/realworldagentshackathon`. Details, rules, and dates: `grants-funding.md`.
- Use cases (push toward **onchain agents** that transact in stablecoins): consumer money (savings, remittance, bill-pay, FX hedging), agentic commerce, DeFAI, prediction markets, freelancer/invoice agents
- **Securing an agent or chatbot**: `agent-security.md` — rendering model output safely, scoping by grounding rather than prompt instructions, treating tool output as untrusted, Denial of Wallet budgeting, and what changes once the agent holds a key (injection reaching a signing path, x402 spend, permanent ERC-8004 reputation). Read it before shipping anything public.
**References**: `ai-agents.md`, `self-agent-id.md`, `agent-vault.md`, `agent-security.md`, `x402-seller-discoverability.md`
### 6. Security & Audit Readiness
Help builders ship safer Celo contracts by flagging Celo-specific risks and pointing to proven audit tooling.
- **Celo-specific risks**: CELO token duality, fee abstraction (CIP-64) accounting, Aave aToken ratio drift, Mento circuit breaker exposure, post-L2 epoch boundary effects
- **General Solidity audit coverage**: defer to `pashov/skills` (https://github.com/pashov/skills) — `solidity-auditor` (8-agent parallel audit) and `x-ray` (threat model + attack surface)
- Use `security-patterns.md` as the Celo layer on top of chain-agnostic audits
- Explicit uncertainty tags on any risk where published specifications are incomplete
- **Off-chain surfaces**: for an LLM agent, assistant, or chatbot, the exploitable surface is usually the renderer, the endpoint, and the prompt rather than the contract — see `agent-security.md`
**References**: `security-patterns.md`, `agent-security.md`
### 7. Governance (Live)
Navigate Celo's on-chain governance system with **live data**.
- **Mondo API**: Fetch all proposals, votes, and execution status from `mondo.celo.org/api/governance/proposals`
- **CGP Repository**: Read full proposal text from `celo-org/governance` on GitHub
- **Forum API**: Get governance discussions from `forum.celo.org/c/governance/12.json`
- Proposal lifecycle, voting, Security Council, epoch rewards
**References**: `governance.md`, `live-data-sources.md`
### 8. Contract Address Lookup
Verified addresses from `docs.celo.org` — core protocol, tokens, L1 bridge, Uniswap, Aave, Morpho.
**References**: `contracts.md`
### 9. Grant & Funding Matchmaking
All active Celo funding programs with a matchmaking guide.
**Always fetch live program status from `celopg.eco/programs`** before answering — program status, dates, and eligibility change mid-quarter and the cached reference goes stale. See `live-data-sources.md` §2.
> **Proof of Ship has been sunset.** If someone asks about it, say so and point them at the Celo Devs newsletter (https://celo-devs.beehiiv.com/subscribe) for hackathon and program announcements. Do not describe it as a route to funding.
**References**: `grants-funding.md`, `live-data-sources.md`
### 10. Documentation Navigation
Structured map of `docs.celo.org` (~150 pages) for finding the exact docs page.
**References**: `docs-map.md`
### 11. Network Information
Chain IDs, RPCs, explorers, faucets, RPC limits (`eth_getLogs` block range), and fee currency addresses.
**References**: `network-info.md`
### 12. Builder Toolkit
Non-protocol-technical guidance that turns a working Celo project into a shipped, growing, sustainable one. Differentiator: not "is your app a good fit?" but "here's the skill, tool, or prompt to make it better." Composes with Capability 4's MiniPay app-fit framework (separate PR by Beni) — that scorecard tells you *whether* to build for MiniPay; this toolkit tells you *how* to make whatever you ship better.
- **Design** (anti-AI-slop): UI/UX Pro Max skill, Anthropic's Claude Design, logo prompts for Gemini/ChatGPT, where Celo's own brand assets live (brand kit, not the archived GitHub repo) and favicon gotchas
- **Comms**: one-sentence pitch forging, build-in-public weekly cadence, launch posts, "strip AI-slop" rewrite prompt
- **GTM**: ICP definition, channel selection for Celo/MiniPay audiences, Remotion + Screen Studio video loop, public MCP servers as a distribution channel
- **Referrals**: dual-sided incentives, 4 referral pattern archetypes (flat bounty / revenue share / fee waiver / leaderboard), leaderboards that don't demotivate the long tail, on-chain tracking patterns, anti-sybil, k-factor metrics
- **Analytics**: PostHog + The Graph + direct RPC three-tier scaling strategy, with full code samples for caching, CORS hardening, and HogQL queries
- **Business model**: MRR-or-die framing, USDT monetization patterns (commission / product sale / subscription / agent calls), break-even calculator
- **Dev methodology**: spec-driven development with Superpowers — ship faster with fewer regressions (see also Capability 2)
- **SEO**: SEO Audit skill + Celo/MiniPay keyword strategy + on-page essentials
Start with `growth-diagnostic.md` — the 6-question diagnostic routes the builder to the right reference. If the builder is asking "should I build for MiniPay?", route them to `minipay-app-fit.md` (Capability 4, separate PR) first — this toolkit assumes a builder past the fit decision.
**References**: `growth-diagnostic.md`, `growth-ux-design.md`, `growth-comms.md`, `growth-gtm.md`, `growth-referrals.md`, `growth-analytics.md`, `business-model.md`, `growth-seo.md`
### 13. Brand & Attribution
Help partners and integrators reference Celo correctly — logos, symbol, colors, and **"Build on Celo"** attribution.
- Point to the official **Celo Brand Kit** (`https://celo.org/brand-kit`) — the canonical, always-current source for downloadable wordmark/symbol assets, colors, and typography
- **Brand policy**: use official assets unmodified (no recoloring, redrawing, or adding elements); don't register Celo marks/domains; don't imply endorsement or a partnership that doesn't exist
- Never hardcode hex values or fonts — send users to the live Color and Typography sections
**References**: `brandkit.md`
### 14. Feedback & Issue Routing
Help the user report a bug or propose a feature and **route it to the right Celo repo** — without leaving their editor.
- Triggers on intent like "report a bug", "request a feature", "something's wrong in the docs / this skill", "file an issue", or "give feedback"
- Routes to the correct destination (this skill → `celo-org/celopedia-skills`, docs → `celo-org/docs`, Celo Composer → `celo-org/celo-composer`, x402 SDK/attribution → `celo-org/attribution-tags`, x402 facilitator/infra → `celo-org/x402-facilitator`)
- Default output is a GitHub **issue**; for small fixes to sources we can edit (this skill's references and the Celo docs), offer a **PR** instead
- Files via `gh`, with a prefilled browser-form fallback; **always confirm the drafted issue with the user and keep it public-safe** (no private names/calls/quotes) before filing
**References**: `feedback.md`
### 15. Migrating a dApp from Another Chain
Help a team **move or expand an existing EVM app onto Celo** from another L2 — Lisk, Base, Optimism, Mode, Ink, Unichain, Soneium, Zora, Fraxtal.
- Triggers on intent like "migrate to Celo", "move my app to Celo", "port this to Celo", "switch chains", "redeploy on Celo", "deploy this on Celo instead", "I'm building on Lisk / Base / Optimism — how do I come to Celo", or "what changes if I run this on Celo"
- **Ask first whether they're fully moving or going multichain** — most teams haven't decided, and it changes the plan
- Audit the repo for chain IDs, RPC hosts, chain-object imports, hardcoded token addresses, and native-gas assumptions; map tokens and protocols; then apply edits in order
- **Two things silently break working code**: the gas token (ETH → CELO, plus CIP-64 fee abstraction) and **CELO token duality** — ported `WETH.deposit{value:}()` reverts, `receive()` never fires on the ERC-20 path, native+ERC-20 balances double-count, and a CELO approval exposes the user's gas money
- Foundry fork tests do **not** simulate the `0xfd` precompile — a fork transfer returns success and moves nothing, so fork-green is not verification
- Never invent a token address or a protocol mapping; if there's no Celo equivalent, say so
**References**: `migrating-from-another-chain.md`, `builder-guide.md`, `contracts.md`, `dev-templates.md`
---
## Research Workflow
### Step 1: Classify the Query
| Need | Action |
|------|--------|
| Ecosystem search / competitors | Query The Grid (`the-grid-skill.md`) |
| Contract address | Look up in `contracts.md` |
| Protocol integration | Check `defi-protocols.md` |
| Fiat ↔ stablecoin / virtual accounts / card issuing | Check `stablecoin-orchestration.md` |
| Getting wARS / wBRL / wMXN / wCOP / wPEN / wCLP, Ripio Ramp or Bridge | Check `wfiat-access.md` — re-run its _Re-verify_ commands before quoting liquidity |
| Bulk payouts / mass distribution / airdrop / "blast sender" / paying thousands of recipients | Check `bulk-payouts.md` |
| Batch / multisend contract address (Disperse, Multicall3, Safe MultiSend, Permit2) | Look up in `contracts.md` → _Batch Distribution & Utility Contracts_ |
| Build / deploy / verify | Check `builder-guide.md`, `dev-templates.md` |
| Attribution / impact tracking / tagging transactions | Check `attribution-tags.md` |
| MiniPay development | Check `minipay-guide.md`, `minipay-templates.md` |
| Specific MiniPay docs page (`docs.minipay.xyz/...`) | Look up in `minipay-docs-map.md` |
| MiniPay app rejected / failing review / "works everywhere except MiniPay" | Check `minipay-common-mistakes.md` — symptom → cause → fix router |
| MiniPay submission / listing readiness | Check `minipay-requirements.md` — ask first if they've had their MiniPay call. If not → Stage 1 intake prep. If yes → full Stage 2 checklist. |
| MiniPay performance / load speed / Web Vitals / PageSpeed / slow first load | Check `minipay-performance.md` — measure real-user load speed with PostHog + optimization playbook to hit 90+ |
| What Mini Apps are live / discovery ideas | Check `minipay-live-apps.md` (snapshot; country availability varies) |
| ODIS / phone lookup / SocialConnect | Check `odis-socialconnect.md`, `minipay-guide.md`, `contracts.md` |
| AI agent building | Check `ai-agents.md` |
| x402 / pay-per-use API / paid endpoints | Check `ai-agents.md` → x402; hosted facilitator guide: `https://x402.celo.org/SKILL.md` |
| Agent needs to PAY for an API or service per request (compute, data, RPC, LLM) / buy / usebuy.ai | Route to buy (AI agents section above) and its skills in `https://github.com/celo-org/buy-skill`. No crypto → the Self-gated USA₮ faucet, then pay in USAT. Building a paid endpoint instead → the x402 row |
| Agent paying by card / agent logging in to websites / Agent Vault / agent shopping safely | Check `agent-vault.md` — not Celo-specific; say so, and route onchain payments to x402 |
| "How do agents find my paid API" / get listed / discoverability / Bazaar / agent402 / x402scan | Check `x402-seller-discoverability.md` — self-describing 402 + index-by-index entry rules |
| Security / audit prep | Check `security-patterns.md` (Celo-specific); defer general Solidity audits to `pashov/skills` |
| Grants / funding / current hackathon (dates, tracks, rules, how to register) | Check `grants-funding.md` — fetch the hackathon page live for deadlines |
| Documentation | Check `docs-map.md` |
| Network config | Check `network-info.md` |
| Governance | Check `governance.md` |
| SDK help | Check `sdk-reference.md` |
| Builder asks about design / UI / "looks bad" / logo | Check `growth-ux-design.md` |
| Celo logo / symbol / brand kit / "which file is the official Celo mark" / favicon for a Celo property | Check `growth-ux-design.md` §6 — source is https://celo.org/brand-kit; `github.com/celo-org/brand` is archived and wrong |
| Builder asks about launch posts / threads / build-in-public | Check `growth-comms.md` |
| Builder asks about first users / distribution / channels / Remotion videos / public MCP servers | Check `growth-gtm.md` |
| Builder asks about referrals / leaderboards / viral loops / share incentives | Check `growth-referrals.md` |
| Builder asks about metrics / dashboards / PostHog / The Graph / RPC scaling | Check `growth-analytics.md` |
| Builder asks about monetization / MRR / USDT revenue / break-even / sustainability | Check `business-model.md` |
| Builder asks about workflow / Superpowers / spec-driven / shipping faster | Check `dev-methodology.md` |
| Builder asks about SEO / Google ranking / meta tags / organic traffic | Check `growth-seo.md` |
| Builder asks general "how do I make my project better?" | Check `growth-diagnostic.md` (routes to the right toolkit file) |
| Branding / logo / "Build on Celo" / brand colors | Check `brandkit.md` |
| Report a bug / request a feature / give feedback | Route via `feedback.md` |
| Moving an app to Celo from another chain ("migrate from Lisk", "port this to Celo") | Follow `migrating-from-another-chain.md` |
### Step 2: Gather Evidence (Prefer Live Data)
**Always prefer live API calls over hardcoded reference files** for data that changes (TVL, prices, grants, protocol status). See `live-data-sources.md` for all available APIs.
| Data Type | Live Source | Fallback |
|-----------|-----------|----------|
| DeFi TVL / protocols | DefiLlama API (`api.llama.fi`) | `ecosystem.md` snapshot |
| Ecosystem products | The Grid GraphQL | `ecosystem.md` snapshot |
| Grant programs | Fetch `celopg.eco/programs` | `grants-funding.md` snapshot |
| Contract addresses | `contracts.md` (stable, rarely changes) | — |
| Docs pages | `curl docs.celo.org/llms.txt` | `docs-map.md` snapshot |
| On-chain data | Celo RPC (`forno.celo.org`) | — |
| Token/contract info | Blockscout API (no key needed) | Celoscan API (key needed) |
| MiniPay discovery listings | MiniPay app in target regions | `minipay-live-apps.md` snapshot |
| Brand assets / colors / logos | Official brand kit (`celo.org/brand-kit`) | `brandkit.md` pointer |
### Step 3: Synthesize & Present
- Lead with the direct answer
- Include contract addresses with chain context
- Link to docs pages for deep dives
- **Flag when using snapshot data** — tell the user if data might be stale and suggest the live source
- Suggest grants if the user is building
---
## Idea Validation Workflow
When a builder has a new idea, guide them through:
1. **Search** — Find existing projects in the space (The Grid + ecosystem directory)
2. **Analyze** — How saturated is this vertical? What's the gap?
3. **Compare** — What exists on other EVM chains but not on Celo?
4. **Fund** — Match to the right grant program
5. **Build** — Set up dev environment (Foundry/Hardhat + Viem)
6. **Integrate** — Add DeFi protocols, MiniPay, or AI agent features as needed
7. **Ship** — Deploy, verify, add attribution tags (`attribution-tags.md`), and point to launch checklist
---
## Important Rules
1. **Never guess contract addresses.** Wrong addresses = lost funds. If not in references, say so.
2. **Celo is an L2, not an L1.** Migrated March 26, 2025 (block 31,056,500). This is **Celo's own** L1→L2 migration — a historical fact about the chain. Don't confuse it with a user migrating *their app* to Celo from another chain, which is `migrating-from-another-chain.md`.
3. **Mento stablecoins rebranded — lead with the m-...
© celo-org · Apache-2.0 · celo-org/celopedia-skills