clerk-common-errors
Troubleshoot common Clerk errors and issues. Use when encountering authentication errors, SDK issues, or configuration problems with Clerk. Trigger with phrases like "clerk error", "clerk not working", "clerk authentication failed", "clerk issue", "fix clerk".
80
77%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/saas-packs/clerk-pack/skills/clerk-common-errors/SKILL.mdQuality
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 solid skill description with excellent trigger terms and completeness. Its main weakness is that the capabilities described are somewhat generic ('troubleshoot common errors') rather than listing specific concrete troubleshooting actions. The Clerk-specific focus gives it strong distinctiveness.
Suggestions
Add specific concrete actions like 'resolve middleware configuration errors, debug token/session issues, fix SDK version conflicts, troubleshoot webhook failures' to improve specificity.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Clerk) and mentions some categories of issues (authentication errors, SDK issues, configuration problems), but doesn't list specific concrete actions like 'resolve middleware conflicts', 'fix token expiration', or 'debug webhook failures'. | 2 / 3 |
Completeness | Clearly answers both 'what' (troubleshoot common Clerk errors and issues) and 'when' (encountering authentication errors, SDK issues, or configuration problems) with explicit trigger phrases listed. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms that users would actually type: 'clerk error', 'clerk not working', 'clerk authentication failed', 'clerk issue', 'fix clerk'. These cover common phrasings well. | 3 / 3 |
Distinctiveness Conflict Risk | Clerk is a specific product/service, and the trigger terms are all Clerk-specific, making it very unlikely to conflict with other skills. The niche is clearly defined. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
64%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 troubleshooting reference with highly actionable, executable code examples covering the most common Clerk errors. Its main weaknesses are the lack of a triage/diagnostic workflow to guide Claude through identifying which error category applies, and some structural bloat from duplicated summary sections. The content would benefit from a clearer 'diagnose first, then fix' flow with verification steps after applying fixes.
Suggestions
Add a brief triage workflow at the top (e.g., 'Check error message → match to category → apply fix → verify fix worked') to improve workflow clarity.
Add explicit verification steps after each fix (e.g., 'After applying, restart dev server and confirm the error is gone') — especially important for middleware and env var issues.
Remove the 'Output' section and consider merging the 'Error Handling' summary table into a more compact quick-reference at the top, eliminating duplication with the detailed sections.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Generally efficient with code-focused solutions, but includes some unnecessary sections like 'Prerequisites', 'Output', and the 'Error Handling' summary table that largely duplicates the detailed sections above. The inline comments explaining causes are useful but some could be tighter. | 2 / 3 |
Actionability | Excellent actionability — every error has executable TypeScript code with specific fixes, a diagnostic bash checklist, and concrete file paths/commands. The code is copy-paste ready and covers real-world scenarios with correct patterns. | 3 / 3 |
Workflow Clarity | The diagnostic checklist at the end provides a clear sequence, but the main content is organized as a reference lookup rather than a workflow. For a troubleshooting skill, there's no explicit triage flow (e.g., 'check this first, then this') or validation steps to confirm fixes worked after applying them. | 2 / 3 |
Progressive Disclosure | Content is well-organized by error category with clear headers, but the skill is quite long (~150 lines of substantive content) and could benefit from splitting detailed error categories into separate files. The reference to 'clerk-debug-bundle' in Next Steps is good, but the inline content is borderline monolithic. | 2 / 3 |
Total | 9 / 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
3e83543
- 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.