clerk-reference-architecture
Reference architecture patterns for Clerk authentication. Use when designing application architecture, planning auth flows, or implementing enterprise-grade authentication. Trigger with phrases like "clerk architecture", "clerk design", "clerk system design", "clerk integration patterns".
74
70%
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-reference-architecture/SKILL.mdQuality
Discovery
75%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 well-structured with explicit 'Use when' and 'Trigger with' clauses, making it complete and distinctive. However, the capabilities described are somewhat vague ('reference architecture patterns') rather than listing concrete actions, and the trigger terms could cover more natural user phrasings beyond formal architecture-level terms.
Suggestions
Add more specific concrete actions, e.g., 'Provides patterns for session management, webhook configuration, multi-tenant auth, SSO integration, and middleware setup with Clerk'.
Expand trigger terms to include more natural user phrases like 'clerk auth', 'clerk setup', 'clerk SSO', 'clerk middleware', 'clerk session', 'how to use Clerk'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Clerk authentication) and mentions some actions like 'designing application architecture', 'planning auth flows', and 'implementing enterprise-grade authentication', but these are fairly high-level and don't list concrete specific actions (e.g., 'configure SSO', 'set up webhook handlers', 'implement session management'). | 2 / 3 |
Completeness | Clearly answers both 'what' (reference architecture patterns for Clerk authentication) and 'when' (designing application architecture, planning auth flows, implementing enterprise-grade authentication) with explicit trigger phrases listed. | 3 / 3 |
Trigger Term Quality | Includes some relevant trigger terms like 'clerk architecture', 'clerk design', 'clerk integration patterns', but misses many natural user phrases like 'clerk setup', 'clerk auth', 'clerk SSO', 'clerk session management', 'clerk middleware', or simply 'authentication with Clerk'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on 'Clerk' specifically as an authentication provider creates a clear niche that is unlikely to conflict with generic auth skills or other authentication provider skills. The trigger terms are Clerk-specific. | 3 / 3 |
Total | 10 / 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 reference architecture skill with excellent actionability — the code examples are complete, realistic, and cover four distinct patterns well. The main weaknesses are the monolithic structure (all four architectures inline rather than split into referenced files) and the lack of explicit implementation workflows with validation checkpoints. Some minor verbosity in prerequisites and output sections could be trimmed.
Suggestions
Split each architecture pattern into its own referenced file (e.g., `arch-nextjs-fullstack.md`, `arch-microservices.md`) and keep SKILL.md as a concise overview with the ASCII diagrams and links to detail files.
Add explicit implementation steps with validation checkpoints for at least one architecture (e.g., '1. Set up ClerkProvider → 2. Add middleware → 3. Verify: visit /protected route, confirm redirect to sign-in → 4. Add webhook → 5. Verify: check DB for synced user').
Remove the 'Prerequisites' section and the 'Output' section — Claude doesn't need to be told what JWT is, and the output section just restates the table of contents.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient with good code examples, but includes unnecessary sections like 'Prerequisites' (Claude knows what JWT and OAuth are), the 'Output' section which just restates what was already shown, and some light padding in the overview. The error handling table and code examples earn their place, but the overall document could be tightened. | 2 / 3 |
Actionability | Excellent actionability — every architecture pattern includes fully executable TypeScript code with correct imports, realistic file paths, and copy-paste ready implementations. The Prisma schema, middleware configurations, and API route handlers are all concrete and complete. | 3 / 3 |
Workflow Clarity | The four architectures are clearly presented with ASCII diagrams showing data flow, and the error handling table provides troubleshooting guidance. However, there are no explicit validation checkpoints or sequenced implementation steps — the content presents patterns rather than step-by-step workflows with verification points (e.g., no 'verify webhook is receiving events before proceeding' type guidance). | 2 / 3 |
Progressive Disclosure | The content is well-structured with clear section headers and four distinct architecture patterns, but it's a long monolithic document (~200 lines of code examples) with no bundle files to offload detail into. Each architecture could be its own referenced file. The 'Resources' section links to external docs and 'Next Steps' references another skill, which is good, but the inline content is heavy. | 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
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.