you-might-not-need-url-state

Analyze and fix URL/query-param state anti-patterns — manual useSearchParams reads, hand-built query mutations, view-state trapped in useState, and objects in the URL

Quality

77%

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/you-might-not-need-url-state/SKILL.md

Quality

Content

87%

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

The content is concise, information-dense, and highly actionable, deferring detail appropriately to a single source-of-truth rule file and nuqs docs. The main gap is the missing validation/verification checkpoint in the fix workflow, which applies mutating changes across files.

Suggestions

Add an explicit verification step to the workflow, e.g., after applying fixes run the typechecker/tests/build and only report success once they pass, with a fix-and-retry loop on failure.

Make the "decision table" referenced in Step 3 explicit (inline a compact table mapping state types to their correct home) rather than only pointing to the rules file, so Claude can decide the correct home without an extra read.

Clarify what "real-chrome fallback" means for the Suspense boundary with a one-line concrete example so the guidance is unambiguous.

Dimension	Reasoning	Score
Conciseness	The body is lean and dense with project-specific conventions Claude would not know (co-located search-params.ts, createSortParams, useUrlSort, useDebouncedSearchSetter, the workflow-editor carve-out) and does not explain basic concepts like React Query or useState, matching the score-3 anchor.	3 / 3
Actionability	Names exact APIs, helper paths, and concrete fix recipes (e.g., "Replace with useQueryState/useQueryStates", "Store the id and derive the object from the loaded list (items.find(i => i.id === id))") with an executable snippet, so per the instruction-only scoring note the guidance is highly actionable.	3 / 3
Workflow Clarity	A clear 4-step sequence is present, but applying fixes across many files is a batch/mutating operation with no explicit validation/verification checkpoint (e.g., typecheck/test/build after fixes), so per the rubric this caps workflow clarity at 2.	2 / 3
Progressive Disclosure	No bundle files exist, but the body serves as a clear overview deferring detail one level deep to well-signaled references (the .claude/rules source-of-truth file and four labeled nuqs doc URLs) in a dedicated numbered References section, with well-organized Context/Anti-patterns/Steps sections.	3 / 3
	Total	11 / 12 Passed

Description

67%

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

The description is specific and distinct, naming concrete anti-patterns and named APIs, but it omits any explicit "when to use this" trigger guidance and relies on internal jargon rather than natural user phrasings. Adding a "Use when..." clause and broader trigger terms would raise completeness and trigger-term quality.

Suggestions

Append an explicit "Use when..." clause (e.g., when working with URL state, query params, shareable tabs/filters/sort, or deep-linkable view-state) so the "when" is stated, not implied.

Broaden trigger terms to include natural user phrasings like "filters", "tabs", "sort", "pagination", "deep links", and "shareable view state" rather than only framework-specific identifiers.

Keep the named anti-patterns but trim the most internal-sounding tokens (e.g., raw API names) in favor of plain-language equivalents to improve natural-keyword coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions ("Analyze and fix") plus named anti-patterns ("manual useSearchParams reads", "hand-built query mutations", "view-state trapped in useState", "objects in the URL"), matching the score-3 anchor for several specific concrete actions.	3 / 3
Completeness	Clearly states what it does but has no "Use when..." clause or equivalent explicit trigger guidance, so per the rubric the missing "when" caps completeness at 2.	2 / 3
Trigger Term Quality	Includes some relevant terms ("URL/query-param state", "useSearchParams", "useState") but leans on framework-specific jargon and misses common natural phrasings a user would say (e.g., "filters", "tabs", "deep links", "shareable view"), matching the score-2 anchor.	2 / 3
Distinctiveness Conflict Risk	Targets a narrow, well-defined niche (URL/query-param state anti-patterns with named APIs) with distinct triggers unlikely to fire for unrelated skills, matching the score-3 anchor.	3 / 3
	Total	10 / 12 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/you-might-not-need-url-state/SKILL.md
Commit: 6f514c1

Reviewed: about 16 hours 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.