clerk-upgrade-migration
Manage Clerk SDK version upgrades and handle breaking changes. Use when upgrading Clerk packages, migrating to new SDK versions, or handling deprecation warnings. Trigger with phrases like "upgrade clerk", "clerk migration", "update clerk SDK", "clerk breaking changes".
85
83%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Quality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a well-structured skill description with clear 'what' and 'when' clauses and explicit trigger phrases. The main weakness is that the capabilities could be more specific—listing concrete actions like updating import paths, replacing deprecated methods, or modifying auth configurations would strengthen it. Overall it's a solid description that would perform well in skill selection.
Suggestions
Add more specific concrete actions beyond 'manage upgrades and handle breaking changes', e.g., 'update import paths, replace deprecated API calls, migrate authentication middleware, update Clerk component usage'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Clerk SDK) and some actions (version upgrades, breaking changes, deprecation warnings), but doesn't list specific concrete actions like 'update import paths', 'replace deprecated API calls', or 'modify configuration files'. | 2 / 3 |
Completeness | Clearly answers both 'what' (manage Clerk SDK version upgrades and handle breaking changes) and 'when' (upgrading Clerk packages, migrating to new SDK versions, handling deprecation warnings), with explicit trigger phrases provided. | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would actually say: 'upgrade clerk', 'clerk migration', 'update clerk SDK', 'clerk breaking changes', 'deprecation warnings'. Good coverage of common variations a user would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Very specific niche targeting Clerk SDK specifically. Unlikely to conflict with generic upgrade or migration skills due to the explicit 'Clerk' branding throughout the description and trigger terms. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a solid, highly actionable skill with excellent workflow clarity and concrete executable examples for Clerk SDK migration. Its main weakness is length — at ~180 lines it packs a lot into a single file that could benefit from splitting migration patterns and the automation script into separate bundle files. The content is slightly verbose in places with commented-out before/after patterns but overall earns its space with genuinely useful, specific guidance.
Suggestions
Extract the automated migration script into a bundle file (e.g., scripts/migrate-clerk-v6.sh) and reference it from the main skill to reduce body length.
Consider moving the detailed v5-to-v6 migration patterns into a separate MIGRATION-V5-V6.md file, keeping only a summary in the main skill body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some unnecessary elements — commented-out 'BEFORE' code alongside 'AFTER' code is somewhat verbose, and the prerequisites section states obvious things like 'current Clerk integration working'. The migration script at the end adds value but the overall document could be tightened by ~20%. | 2 / 3 |
Actionability | Excellent actionability throughout — every step includes executable bash commands or complete TypeScript code snippets. The grep commands for finding affected files, the sed-based migration script, and the concrete before/after code examples are all copy-paste ready. | 3 / 3 |
Workflow Clarity | Clear 7-step sequence with explicit validation checkpoints: Step 6 includes build verification, test execution, and a manual testing checklist for critical flows. Step 7 provides a concrete rollback plan. The workflow has a proper feedback loop — build to catch errors, then fix, with rollback if needed. | 3 / 3 |
Progressive Disclosure | The document is fairly long and monolithic — the migration patterns, error handling table, and automated migration script could be split into separate referenced files. However, the structure within the single file is well-organized with clear headers. No bundle files exist to offload content to, and the Resources section provides external links but no internal file references. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Commit
3a2d27d
- 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.