Design Uniswap Hook

Design a Uniswap V4 hook architecture without code generation. Use when user wants to plan a hook, understand which callbacks to use, or review an architecture before building. Returns a design document, not code.

Security Scan

The skill's requests and runtime instructions are consistent with its stated purpose (producing a design document for Uniswap V4 hooks) and it does not ask for credentials, install code, or perform unexpected actions.

Purpose & Capability

Name/description (design Uniswap V4 hook architecture) align with the actual behavior: it is instruction-only, requests parameters about hook behavior/constraints/integrations, and delegates to a 'hook-builder' subagent for producing a design document. The declared allowed tools (a Task subagent and an mcp__uniswap__get_supported_chains helper) are relevant to the stated purpose.

Instruction Scope

SKILL.md stays within scope: extract parameters, invoke a design-only hook-builder subagent, and return a structured design doc. It explicitly forbids code generation and file writes. Minor note: the allowed-tools list includes Read/Glob/Grep which could be used to read files if the agent were instructed to do so, but the SKILL.md does not instruct arbitrary file reads or access to unrelated system data.

Install Mechanism

No install spec and no code files — instruction-only skill. This is the lowest-risk model and matches the declared behavior (design document only).

Credentials

The skill requests no environment variables, no credentials, and no config paths. That is proportionate for a design/documentation task and matches the SKILL.md claims.

Persistence & Privilege

always is false and the skill does not request persistent presence, system config changes, or other skills' credentials. disable-model-invocation is false (normal), and there is no instruction to modify agent-wide settings or store tokens.

Assessment

This skill appears coherent and low-risk: it only produces a design document and asks for no secrets or installs. Before using it, confirm you are comfortable with the agent delegating to the 'hook-builder' subagent (verify that subagent's behavior/policies if possible), avoid pasting private keys or proprietary secrets into prompts, and if you need absolute assurance, ask the skill to explicitly confirm it will not write files, perform network calls, or generate code before proceeding.

Design Hook

Overview

Designs a Uniswap V4 hook architecture without generating code. Delegates to the hook-builder agent in design-only mode to produce a comprehensive design document covering: which callbacks are needed, hook flag requirements, state management approach, gas estimates, security considerations, and architecture decisions. Use this to plan before building, or to evaluate feasibility.

When to Use

Activate when the user asks:

• "Design a hook for..."
• "What callbacks do I need for..."
• "Hook architecture for..."
• "Plan a V4 hook"
• "Is it possible to build a hook that..."
• "What would a dynamic fee hook look like?"
• "Help me think through a hook design"
• "Which flags do I need for a TWAMM?"

Parameters

Parameter	Required	Default	Description
behavior	Yes	--	Hook behavior description (e.g., "limit orders", "dynamic fees", "oracle pricing")
constraints	No	--	Gas budget, security requirements, or specific design constraints
integrations	No	--	External systems the hook needs to interact with (oracles, governance, staking)

Workflow

1. Extract parameters from the user's request: identify the hook behavior, constraints, and any external integrations.

2. Delegate to hook-builder in design-only mode: Invoke Task(subagent_type:hook-builder) with explicit instruction to produce a design document only -- no code generation, no file writes. The hook-builder will:

   • Analyze the requirements and determine which V4 callbacks are needed
   • Map callbacks to hook flags and validate the combination
   • Design the state management approach (what storage, what data structures)
   • Estimate gas overhead per callback
   • Identify security considerations specific to this hook design
   • Evaluate feasibility and flag any concerns

3. Present the design document to the user covering:

   • Callbacks needed and why each is required
   • Hook flags and bitmask
   • State management design (storage variables, data structures, access patterns)
   • Gas estimates and performance implications
   • Security considerations and mitigations
   • Architecture decisions with rationale
   • Comparison with alternative approaches if applicable

Output Format

Present a structured design document:

V4 Hook Design: Dynamic Fee Hook

  Callbacks Required:
    - beforeSwap: Read volatility oracle, calculate dynamic fee
    - beforeInitialize: Set initial fee parameters and oracle address

  Hook Flags: BEFORE_SWAP_FLAG | BEFORE_INITIALIZE_FLAG
  Bitmask: 0x2080

  State Management:
    - volatilityOracle: IVolatilityOracle (immutable, set in constructor)
    - baseFee: uint24 (configurable by owner)
    - maxFee: uint24 (cap to prevent excessive fees)
    - feeMultiplier: uint24 (scales with volatility)

  Gas Estimates:
    beforeSwap: ~30,000 gas (oracle read + fee calculation)
    beforeInitialize: ~25,000 gas (one-time setup)

  Security Considerations:
    - Oracle manipulation: Use TWAP, not spot price
    - Fee cap: Enforce maxFee to protect traders
    - Owner control: Fee parameters updatable by owner only

  Architecture Decisions:
    - Using beforeSwap (not afterSwap) to set fee before execution
    - External oracle for volatility data rather than on-chain calculation
    - Fee bounded between baseFee and maxFee for predictability

  Alternative Approaches:
    - On-chain volatility calculation (higher gas, no oracle dependency)
    - Fixed fee tiers with governance voting (simpler, less responsive)

Important Notes

• This skill produces a design document only -- no code is generated and no files are written.
• The design document provides enough detail to proceed with build-hook when the user is ready.
• If the hook design is infeasible (e.g., requires callbacks that V4 doesn't support), this will be clearly communicated.
• Gas estimates are approximations based on typical implementations -- actual gas depends on implementation details.

Error Handling

Error	User-Facing Message	Suggested Action
VAGUE_REQUIREMENTS	"Need more detail about the desired hook behavior."	Describe specific behavior (e.g., "limit orders that execute at tick boundaries")
UNSUPPORTED_CALLBACK	"V4 does not support the requested callback."	Review available V4 callbacks and adjust requirements
INFEASIBLE_DESIGN	"This hook design is not feasible with current V4 capabilities."	Simplify requirements or consider alternative approaches