chainlink-vrf-skill

name	chainlink-vrf-skill
description	Help developers integrate Chainlink VRF into smart contracts. Use for consumer contract generation with VRFConsumerBaseV2Plus, subscription setup and funding (LINK or native), keyHash and gas lane selection, coordinator address lookup and debugging VRF integrations. Trigger on any mention of VRF, verifiable randomness, on-chain random number generation, requestRandomWords, fulfillRandomWords, VRF subscription, VRF coordinator, keyHash, or provably fair randomness in a smart contract, even if the user does not say 'VRF' explicitly.
license	MIT
compatibility	Designed for AI agents that implement https://agentskills.io/specification, including Claude Code, Cursor Composer, and Codex-style workflows.
allowed-tools	Read WebFetch Write Edit Bash
metadata	{"purpose":"Chainlink VRF v2.5 developer assistance and reference","version":"0.0.2"}

Chainlink VRF Skill

Overview

Route VRF requests to the simplest valid path. Generate working VRF v2.5 code on first attempt when possible. Detect legacy V1/V2 patterns and refuse to emit them — offer migration guidance instead.

Progressive Disclosure

1. Keep this file as the default guide.
2. Read references/subscription.md only when the user wants to build a subscription-based consumer, manage a subscription, use VRFConsumerBaseV2Plus, call requestRandomWords, or handle the fulfillRandomWords callback.
3. Read references/direct-funding.md only when the user wants direct funding (no subscription), uses VRFV2PlusWrapperConsumerBase, or asks about a one-off randomness request.
4. Read references/migration-from-v2.md when you detect V1 or V2 patterns in user-supplied code (VRFConsumerBaseV2, VRFConsumerBase, positional requestRandomWords, uint64 subscription IDs, VRFV2WrapperConsumerBase, or memory randomWords in a subscription consumer) or when the user asks how to migrate.
5. Read references/billing.md only when the user asks about costs, LINK vs native payment, subscription funding, or premium percentages.
6. Read references/supported-networks.md only when the user needs coordinator addresses, wrapper addresses, LINK token addresses, or key hashes for a specific network.
7. Read references/security-and-best-practices.md only when the agent is developing consumer contracts with this skill and when the user asks about security, bias resistance, gas limit sizing, request cancellation, or production readiness.
8. Read references/official-sources.md only when the answer depends on live data the reference files do not contain.
9. Do not load reference files speculatively.

Routing

1. Subscription (default): Use for recurring randomness, games, lotteries, any contract that requests randomness more than once. Route to subscription.md.
2. Direct funding: Use for one-off requests or when the user explicitly does not want a subscription. Route to direct-funding.md.
3. Migration: Detect legacy patterns (see Progressive Disclosure rule 4). Refuse to generate V2 code; load migration-from-v2.md and offer a v2.5 upgrade.
4. Network lookup: When an address or key hash is needed, load supported-networks.md. Never invent coordinator or wrapper addresses.
5. Ask one focused question if the method (subscription vs direct) or target network is unclear and the answer would materially change the code.
6. Proceed without asking for read-only work: explanations, code generation, debugging.

Legacy Pattern Guard

VRF V1 and V2 code will not compile against current v2.5 coordinators. Detect and refuse these patterns:

V2 Pattern	Why it breaks in v2.5
VRFConsumerBaseV2 base	Replaced by VRFConsumerBaseV2Plus
VRFConsumerBase base	V1 — entirely incompatible
Positional requestRandomWords(keyHash, subId, ...)	Must use VRFV2PlusClient.RandomWordsRequest struct
uint64 s_subscriptionId	Sub IDs are now uint256
VRFV2WrapperConsumerBase(linkAddress, wrapperAddress)	No LINK address in v2.5 wrapper constructor
uint256[] memory randomWords in subscription fulfill	VRFConsumerBaseV2Plus uses calldata; direct-funding wrapper consumers still use memory
COORDINATOR as a typed state variable	Use s_vrfCoordinator from the base class

When any of these are detected in user code: (1) name the incompatibility explicitly, (2) load migration-from-v2.md, (3) produce v2.5 code only.

Safety Defaults

These are non-negotiable in generated code.

1. Never invent coordinator, wrapper, or LINK token addresses. Always load supported-networks.md or direct the user to the official addresses page.
2. Use VRFConsumerBaseV2Plus for subscription consumers and VRFV2PlusWrapperConsumerBase for direct-funding consumers (never V1/V2 base contracts).
3. For subscription consumers, always use VRFV2PlusClient.RandomWordsRequest struct with extraArgs (never positional args).
4. Always use uint256 for subscription IDs (never uint64).
5. Use the callback data location required by the base contract: calldata for VRFConsumerBaseV2Plus, memory for VRFV2PlusWrapperConsumerBase.
6. Remind users that example code is unaudited and not for production use without a security review.
7. Do not use block.prevrandao, block.difficulty, or blockhash as a randomness fallback.

Documentation Access

This skill references official VRF documentation URLs throughout its reference files.

1. If WebFetch, a browser tool, or an MCP server that can retrieve documentation is available, use it to fetch the referenced URL before answering.
2. If no documentation-fetching tool is available, do not silently improvise VRF patterns from training data alone. Instead:
   • Use the embedded reference content in this skill's reference files as the floor for guidance.
   • Tell the user that live documentation could not be verified.
   • Provide the specific URL so the user can check it directly.
3. For contract-first workflows where correctness matters most, prefer the concrete examples in references/subscription.md or references/direct-funding.md over generating patterns from memory.

Working Rules

1. Generate working code from knowledge and reference files first. Fetch only when a specific detail is missing.
2. Treat 0-1 fetches as normal, 2-3 as the ceiling. Most questions need no fetches because the reference files contain the implementation guidance.
3. When a fetch is needed, apply the cascade: WebFetch first; if it returns <1000 chars of useful content, fall back to curl -s -L -A "Mozilla/5.0 ..." "<url>"; if both fail, the Context7 MCP server (@upstash/context7-mcp) is a useful fallback for fetching current Chainlink documentation. If no documentation-fetching tool is available, do not silently improvise, instead tell the user that live documentation could not be verified and provide the specific URL so the user can check it directly.
4. Keep answers proportional — a simple "request a random number" question gets a code block and brief explanation, not a full tutorial.
5. Generate code only when code is actually needed.
6. If the user asks to write, build, create, or show a VRF contract or snippet without naming a repository path or file to edit, answer inline with code. Do not ask for filesystem write approval unless the user explicitly asks you to modify files.
7. Keep unsupported or out-of-scope features (off-chain VRF, non-EVM VRF) out of the answer rather than speculating.