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