sw-best-practices

Service Worker practical specifications for the current Magic Web implementation. Covers static resource partitioning, read-only API caching, request tagging, server-side kill/off takeover for /sw.js, and emergency rollback environment variables.

Quality

72%

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 ./frontend/magic-web/.agents/skills/sw-best-practices/SKILL.md

Quality

Content

77%

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

The body is highly actionable with concrete commands, file paths, and well-sequenced SOPs that include validation checkpoints, but it is a monolithic single-file spec with some redundancy and no progressive disclosure into bundle references.

Suggestions

Move the detailed environment-variable semantics (§1.3.1) and the physical architecture map (§2.1) into a referenced reference file (e.g., references/architecture.md) so SKILL.md stays a lean overview and progressive disclosure reaches 3.

De-duplicate the MAGIC_SW_MODE/kill/off behavior described in §1.3.1 and the Emergency SOP (§4) by defining it once and cross-referencing, to tighten conciseness.

Add an explicit post-rollback verification step to the Emergency SOP (e.g., confirm caches cleared / app loads cleanly) so the destructive cache-clearing workflow has a feedback loop rather than only cautions.

Dimension	Reasoning	Score
Conciseness	The body is densely packed with project-specific operational detail and avoids explaining generic Service Worker concepts Claude already knows, but at ~130 lines it repeats information (the MAGIC_SW_MODE/kill/off semantics appear in both §1.3.1 and §4) and could be tightened, matching the "mostly efficient but could be tightened" anchor.	2 / 3
Actionability	It provides concrete file paths (sw-constants.ts, cache-runtime.ts), exact commands ("pnpm test src/workers/service-worker/__tests__/sw-constants.test.ts", "pnpm build"), precise env-var values, and an executable regex example, making the guidance copy-paste ready.	3 / 3
Workflow Clarity	SOPs A/B/C and the Emergency SOP are clearly numbered and sequenced, with SOP C including explicit validation checkpoints (a three-test unit trio and a production build that "must be executed before submission"), matching the anchor for a clear sequence with explicit validation steps.	3 / 3
Progressive Disclosure	No bundle files exist and all content lives inline in SKILL.md; while it is well-sectioned, material that could be split out (the detailed env-var semantics table, the physical architecture map) is inline, and the in-document links point to repo source files rather than one-level-deep skill reference docs.	2 / 3
	Total	10 / 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 well-differentiated, naming concrete capability areas tied to a particular implementation, but it lacks explicit "when to use" trigger guidance and relies on technical jargon over natural user phrasings.

Suggestions

Append a "Use when..." clause listing natural trigger phrases (e.g., "Use when modifying cache rules, adding API caching, troubleshooting the Service Worker, or running an emergency SW rollback") to raise completeness to 3.

Replace or supplement jargon ("server-side kill/off takeover for /sw.js", "request tagging") with terms users actually say, such as "clear SW", "PWA cache", or "SW rollback".

Add a brief mention of the key kill-switch environment variables (MAGIC_SW_MODE, MAGIC_SW_CLEAR_CACHES) as trigger tokens, since users may invoke the skill by naming them directly.

Dimension	Reasoning	Score
Specificity	The description enumerates multiple concrete capability areas — "static resource partitioning, read-only API caching, request tagging, server-side kill/off takeover for /sw.js, and emergency rollback environment variables" — matching the anchor for listing several specific concrete actions rather than vague language.	3 / 3
Completeness	It clearly answers "what" (Service Worker practical specifications covering the listed areas) but provides no "Use when..." clause or equivalent explicit trigger guidance, so per the judging guidelines completeness is capped at 2.	2 / 3
Trigger Term Quality	It includes some relevant keywords a user might say ("Service Worker", "API caching", "rollback") but leans on technical jargon ("server-side kill/off takeover for /sw.js", "request tagging") and omits common natural variations like "PWA", "cache rules", or "SW troubleshooting" that the body itself lists.	2 / 3
Distinctiveness Conflict Risk	It is anchored to "the current Magic Web implementation" with highly specific artifacts (/sw.js, named environment variables), giving it a clear niche that is unlikely to trigger for unrelated skills.	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
relative_links	Relative link issues: 10 suspicious	Warning

	Total	15 / 16 Passed

Repository: dtyq/magic
Path: frontend/magic-web/.agents/skills/sw-best-practices/SKILL.md
Commit: 41d7ef4

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