React Hook Form Best Practices Skill

Corrective guidance for React Hook Form — the decisions that go wrong by default.

Overview

This skill provides 35 rules across 7 categories. Every rule names a decision that a capable model gets wrong by default; rules that merely restated correct library behaviour were removed in 2.0.0. Verified against react-hook-form 7.82.0 (July 2026), with every code block type-checked under tsc --strict against the real package types.

Directory Structure

react-hook-form/
├── SKILL.md                    # Entry point with quick reference
├── AGENTS.md                   # Compiled comprehensive guide (TOC over references/)
├── metadata.json               # Version, org, references
├── README.md                   # This file
├── assets/
│   └── templates/
│       └── _template.md        # Rule template
└── references/
    ├── _sections.md            # Category definitions and impact ordering
    ├── formcfg-*.md            # Form configuration rules (9)
    ├── sub-*.md                # Field subscription rules (7)
    ├── ctrl-*.md               # Controlled component rules (2)
    ├── valid-*.md              # Validation pattern rules (4)
    ├── formstate-*.md          # State management rules (6)
    ├── array-*.md              # Field array rules (4)
    └── integ-*.md              # Integration pattern rules (3)

Validating

This skill is validated by the repo-level tooling, not by per-skill scripts:

npm run validate                                     # structural validation of every skill
node /path/to/dev-skill/scripts/validate-skill.js .  # discipline-aware validation of this skill

Creating a New Rule

Choose the appropriate category prefix:

Category	Prefix	Impact
Form Configuration	`formcfg-`	CRITICAL
Field Subscription	`sub-`	CRITICAL
Controlled Components	`ctrl-`	HIGH
Validation Patterns	`valid-`	HIGH
State Management	`formstate-`	MEDIUM-HIGH
Field Arrays	`array-`	MEDIUM-HIGH
Integration Patterns	`integ-`	MEDIUM

Create a new file: references/{prefix}-{slug}.md
Use the rule template from assets/templates/_template.md
Add the rule to the SKILL.md quick reference and to the AGENTS.md table of contents (entries are ordered alphabetically by title within each section).

Rule File Structure

---
title: Rule Title Here
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: What the rule prevents or enables
tags: prefix, keyword1, keyword2
---

## Rule Title Here

Brief explanation of WHY this matters (1-3 sentences).

**Incorrect (description of problem):**

\`\`\`typescript
// Bad code with comment on key line
\`\`\`

**Correct (description of solution):**

\`\`\`typescript
// Good code with minimal diff from incorrect
\`\`\`

Reference: [Documentation Link](https://example.com)

File Naming Convention

Rules follow the pattern: {prefix}-{slug}.md

prefix: Category identifier from _sections.md (lowercase letters only)
slug: Kebab-case description of the rule

Examples:

formcfg-validation-mode.md
sub-usewatch-over-watch.md
ctrl-usecontroller-isolation.md

Impact Levels

Level	Description
CRITICAL	Cascade effect on entire form performance
HIGH	Significant impact on specific operations
MEDIUM-HIGH	Notable improvement for common patterns
MEDIUM	Measurable improvement in specific scenarios
LOW-MEDIUM	Minor optimization for edge cases
LOW	Best practice with minimal performance impact

Companion Skill

react-hook-form-audit is a static-analysis skill that detects violations of these rules in a Next.js App Router codebase and links each finding back to the corresponding file in references/.

Contributing

Read existing rules in the same category for style consistency
Ensure incorrect/correct examples have minimal diff
Typecheck every example against the pinned react-hook-form version before committing
Include authoritative reference links
Run validation before submitting

Acknowledgments

Based on official React Hook Form documentation, the library's shipped type definitions, and community best practices.

4.3 KiB Raw Blame History