clerk-incident-runbook
Manage incident response for Clerk authentication issues. Use when handling auth outages, security incidents, or production authentication problems. Trigger with phrases like "clerk incident", "clerk outage", "clerk down", "auth not working", "clerk emergency".
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-incident-runbook/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 description excels at trigger term coverage and completeness, with explicit 'Use when' and 'Trigger with' clauses that make it easy for Claude to select appropriately. Its main weakness is the lack of specific concrete actions — it says 'manage incident response' but doesn't enumerate what that entails (e.g., checking status pages, diagnosing errors, implementing workarounds, escalating). The distinctiveness is strong due to the narrow Clerk + incident scope.
Suggestions
Add specific concrete actions to improve specificity, e.g., 'Diagnoses auth failures, checks Clerk service status, implements fallback authentication, coordinates incident communication, and guides recovery steps.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Clerk authentication incident response) and a general action ('manage incident response'), but does not list specific concrete actions like 'diagnose auth failures', 'check API status', 'rotate keys', or 'escalate to Clerk support'. The capabilities remain at a high level. | 2 / 3 |
Completeness | Clearly answers both 'what' (manage incident response for Clerk authentication issues) and 'when' (handling auth outages, security incidents, production auth problems) with explicit trigger phrases listed. The 'Use when' and 'Trigger with' clauses are both present and well-defined. | 3 / 3 |
Trigger Term Quality | Includes a strong set of natural trigger terms users would actually say: 'clerk incident', 'clerk outage', 'clerk down', 'auth not working', 'clerk emergency'. Also includes broader terms like 'auth outages', 'security incidents', and 'production authentication problems', providing good coverage of natural language variations. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — scoped specifically to Clerk authentication incidents, which is a narrow niche. The combination of 'Clerk' + 'incident response' + specific trigger phrases makes it very unlikely to conflict with general auth skills or general incident response skills. | 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 incident runbook with highly actionable, executable code and clear categorization of incident types. Its main weaknesses are the lack of explicit validation/verification steps after critical operations (bypass activation, key rotation, session revocation) and the monolithic structure that could benefit from splitting detailed procedures into separate files. The post-incident template, while useful, adds bulk that Claude could generate without instruction.
Suggestions
Add explicit verification steps after each critical action — e.g., after activating emergency bypass, include a curl command to confirm requests are passing through; after key rotation, verify the new key works with an API call.
Split the detailed procedures (emergency bypass, key rotation, session recovery) into separate referenced files to improve progressive disclosure and reduce the main skill's token footprint.
Remove or significantly shorten the post-incident review template — Claude can generate this format without a full template; a brief note about what to include would suffice.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient with actionable content, but includes some unnecessary elements like the post-incident review markdown template (which Claude could generate on the fly) and some verbose echo statements in scripts. The triage table and error handling table are well-structured and earn their tokens, but the overall length could be tightened. | 2 / 3 |
Actionability | Provides fully executable bash scripts, TypeScript code for middleware bypass and session revocation, concrete curl commands, and specific deployment commands (Vercel). The triage script, emergency bypass middleware, and session recovery endpoint are all copy-paste ready with real API calls. | 3 / 3 |
Workflow Clarity | Steps are clearly numbered and sequenced, and the triage table effectively categorizes incidents by severity. However, there are no explicit validation checkpoints between steps — for example, after activating emergency bypass there's no verification step to confirm it's working, and after key rotation there's no automated validation that the new key is functional. For destructive/critical operations like auth bypass and key rotation, this gaps caps the score at 2. | 2 / 3 |
Progressive Disclosure | The content is well-structured with clear headers and a logical flow, but it's quite long and monolithic. The triage script, emergency bypass code, session recovery endpoint, and key rotation procedure could each be separate referenced files. The mention of 'clerk-observability' in Next Steps hints at cross-referencing but the main content is all inline. | 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.