CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

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
SKILL.md
Quality
Evals
Security

Quality

Content

82%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, highly actionable specification that succeeds on repo-specific concrete detail: exact commands, env blocks, bucket names, and file responsibilities, with sequenced SOPs and an explicit pre-submission verification flow plus a careful emergency rollback plan. Remaining gaps are modest: trim emphatic padding, add an explicit fix-and-re-run loop to the verification SOP, and consider splitting env-var semantics or the architecture map into a reference file.

Suggestions

In SOP C, add an explicit feedback loop after the test commands, e.g. "If any test fails, fix the rule or interceptor and re-run all three before proceeding to the build check."

Trim repeated emphatic framing ("must be strictly followed", "strictly prohibited", duplicated emphasis in section intros) and drop either the mermaid diagram or the bullet file map, since they convey the same structure twice.

Move the environment-variable semantics (section 1.3.1) into a references file (e.g. references/env-vars.md) and keep a one-line summary per variable in SKILL.md, turning the main file into a leaner overview.

DimensionReasoningScore

Conciseness

Nearly every token carries repo-specific information Claude cannot know (bucket names, env-var semantics, SOP commands, file responsibilities), with only minor trimmable padding such as repeated emphasis ("must be strictly followed", "strictly prohibited") and the mermaid diagram partially duplicating the file-map bullets beneath it. Not 5 because those few instances of over-explanation and redundancy could be cut.

4 / 5

Actionability

Fully executable throughout: copy-paste-ready test and build commands, exact env configuration blocks for kill/off/clear-caches, a strict-anchored regex example, and precise file paths and function names (isCacheableApiRequest, cacheWillUpdate, MANAGED_APP_CACHE_NAMES). Common cases (adding a cached API, adding a bucket, verifying changes, emergency rollback) are each covered with concrete commands; the only minor gap is the absence of a registration snippet in SOP A step 2, which the surrounding specificity still makes actionable.

5 / 5

Workflow Clarity

SOPs A/B/C and the two-line-of-defense emergency plan are clearly sequenced, SOP C is an explicit pre-submission validation checkpoint with concrete commands, and the destructive kill/ALL path carries an explicit caution. Falls just short of anchor 5 because the verification flow lacks an explicit feedback loop ("if tests fail, fix and re-run") — validation is present but error recovery is only implied.

4 / 5

Progressive Disclosure

No bundle files are provided (references/, scripts/, assets/ are absent), and the single file is organized into clearly headed, numbered sections with a well-signaled, one-level-deep map of project source files and their roles. Not 5 because the ~135-line document monolithically inlines content (environment-variable semantics, the architecture map, SOP detail) that could be offloaded to reference files to keep SKILL.md a leaner overview.

4 / 5

Total

17

/

20

Passed

Description

70%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 specific, distinctive, third-person description that clearly conveys what the skill covers for this particular project. Its main weakness is the complete absence of "when to use" trigger guidance, which both caps completeness and leaves natural trigger phrasing (PWA, offline, cache rules) out of the description even though the body contains an activation-keywords section.

Suggestions

Add an explicit trigger clause to the description, e.g. "Use when modifying Service Worker cache rules, troubleshooting SW caching, or rolling back SW changes in this repository."

Surface the body's activation keywords ("modify cache rules", "clear SW", "MAGIC_SW_MODE") into the description so natural trigger terms are discoverable at the skill-listing level.

Keep the description in the third person and avoid adding more topic enumeration; consolidate the five capability areas if the trigger clause makes some redundant.

DimensionReasoningScore

Specificity

Lists five 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") with a named artifact. Not 5 because these are topic areas introduced by "Covers" rather than concrete actions, and capabilities like registration gating and verification appear only in the body, not the description.

4 / 5

Completeness

The "what" is clear and concrete, but the description contains no "Use when..." clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines. It is not 4 because the "when" is entirely absent from the description rather than merely imprecise.

3 / 5

Trigger Term Quality

Includes specific, naturally searchable terms ("Service Worker", "API caching", "/sw.js", "rollback", "request tagging"). A few common variations users would actually say are missing, such as "PWA", "offline", "Workbox", or "cache rules", so it does not reach comprehensive anchor-5 coverage.

4 / 5

Distinctiveness Conflict Risk

Occupies a clear niche (Service Worker caching for one named "Magic Web" implementation) with project-specific mechanisms (/sw.js takeover, rollback environment variables), making conflict with other skills minimal.

5 / 5

Total

16

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

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

Reviewed

Table of Contents

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.