Chainlink Vrf Skill

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](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](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](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](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](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](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](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.

1. For contract-first workflows where correctness matters most, prefer the concrete examples in [references/subscription.md](references/subscription.md) or [references/direct-funding.md](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 "; 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.

Source & license

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

• Author: smartcontractkit
• Source: smartcontractkit/chainlink-agent-skills
• License: MIT

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