react-query-best-practices

Audit React Query usage for best practices — key factories, staleTime, mutations, and server state ownership

Quality

65%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/react-query-best-practices/SKILL.md

Quality

Content

68%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A dense, expert-level ruleset that is highly actionable and respects the reader's intelligence — nearly every line encodes a non-obvious project decision rather than general knowledge. The gaps are a workflow with no validation step despite defaulting to applying fixes, and a rules section that is heavy for a single file with no bundle to distribute it into.

Suggestions

Add a verification step after applying fixes, e.g. "4. Run typecheck/tests on the changed files and re-audit the scope to confirm no rule violations remain" — especially important since fix defaults to true.

Tighten the multi-clause parenthetical rules (lines 30, 33, 37) into shorter single-purpose bullets so each rule is scannable on first read.

If the skill grows, move the detailed query-key/mutation rules into a references/ file and keep SKILL.md as the overview, which would also make the delegation to `.claude/rules/sim-queries.md` less load-bearing.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes competence: it never explains what React Query is or how it works, and every rule adds non-obvious, project-specific constraints (e.g. "a 'use client' export called from the server crashes SSR"). It falls short of anchor 5 because several rules are packed into long parenthetical sentences (lines 30, 33, 37) that require re-reading to parse and could be tightened.	4 / 5
Actionability	Mostly concrete and executable: exact expressions like "Boolean(id) && (options?.enabled ?? true)", concrete module paths ("hooks/queries/utils/"), specific APIs ("queryClient.prefetchQuery", "onSettled"), and unambiguous do/don't pairs. It is not fully copy-paste ready at anchor 5 because enforcement details are delegated to the external `.claude/rules/sim-queries.md` and there are no complete code examples showing a correct hook inline.	4 / 5
Workflow Clarity	The three-step sequence (read references, analyze scope, apply or propose fixes) is clear, but it has no validation checkpoints. Because the skill defaults to fix=true and applies changes across a whole scope (a batch modification), the missing verification step (e.g. re-check types/tests after fixes) caps workflow clarity at 3 per the feedback-loops guideline.	3 / 5
Progressive Disclosure	No bundle files exist, and the body is well-organized into Context, References, Rules, and Steps with clearly signaled one-level-deep references (three named tkdodo.eu URLs with what each covers, plus explicitly scoped pointers to `.claude/rules/sim-queries.md` sections). Not anchor 5 because the dense Rules sections are somewhat monolithic — the query-key rules would sit more naturally in a separate reference file if a bundle existed — and the mandatory "read these before analyzing" external URLs make the entry point depend on outside navigation.	4 / 5
	Total	15 / 20 Passed

Description

61%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A concise, domain-specific description that clearly states what the skill does and names the concrete areas it audits. Its main weakness is the complete absence of a "Use when..." trigger clause, plus missing common synonyms like "TanStack Query" and "query keys".

Suggestions

Add an explicit trigger clause, e.g. "Use when reviewing React Query code, writing query hooks, or debugging stale cache or invalidation issues."

Include the synonym "TanStack Query" and common user phrases like "query keys", "cache invalidation", and "prefetching" so the description matches how users actually ask.

Consider naming one or two concrete actions beyond "audit" (e.g. "find and fix") to sharpen the capability list.

Dimension	Reasoning	Score
Specificity	"Audit React Query usage for best practices" names the domain and one concrete action, and the dash-listed "key factories, staleTime, mutations, and server state ownership" are specific topic areas, but there is only a single action verb rather than the several distinct actions of anchor 4. The enumerated topics give it real coverage beyond the generic anchor-3 example, but 'audit ... for best practices' remains one operation, not a list of capabilities.	3 / 5
Completeness	The 'what' is clear — audit React Query usage against best practices — but there is no "Use when..." clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines. It is a strong anchor-3 case: clear what, 'when' entirely absent rather than weakly implied.	3 / 5
Trigger Term Quality	"React Query", "staleTime", "mutations", "key factories", and "server state" are terms users of this library genuinely say. Missing natural synonyms and variations such as "TanStack Query", "query keys", "invalidation", or "prefetch", which keeps it short of comprehensive coverage at anchor 5.	4 / 5
Distinctiveness Conflict Risk	"React Query" plus "staleTime" and "key factories" carve out a clear niche that few other skills would claim, and a user mentioning these terms almost certainly means this skill. Minor overlap risk remains with generic React or state-management best-practices skills ("server state", "best practices"), keeping it below the minimal-conflict anchor 5.	4 / 5
	Total	14 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: simstudioai/sim
Path: .agents/skills/react-query-best-practices/SKILL.md
Commit: 8725250

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.