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 completeness and distinctiveness by clearly specifying both what the skill does and when to use it, with explicit trigger phrases tied to a specific product (Clerk). Its main weakness is the lack of specific concrete actions—it says 'manage incident response' without detailing what that management entails (e.g., checking status pages, reviewing logs, rotating credentials, communicating with stakeholders).
Suggestions
Add specific concrete actions the skill performs, e.g., 'diagnose auth failures, check Clerk API status, review error logs, coordinate rollback or key rotation' to improve specificity.
| 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' (explicit 'Use when' clause with trigger scenarios and a 'Trigger with phrases like' section listing specific phrases). Both dimensions are explicitly addressed. | 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', plus broader terms like 'auth outages', 'security incidents', and 'production authentication problems'. Good coverage of natural language variations. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive due to the specific combination of 'Clerk' (a named product) and 'incident response'. The trigger terms are narrowly scoped to Clerk-specific authentication emergencies, making 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) and the monolithic structure that could benefit from splitting detailed scripts and templates into separate bundle files. Some minor verbosity could be trimmed without losing clarity.
Suggestions
Add explicit validation checkpoints after critical operations — e.g., after activating emergency bypass, include a curl command to verify the bypass header is present; after key rotation, verify the new key works with an API call.
Split the triage script, session recovery endpoint, and post-incident template into separate bundle files referenced from SKILL.md to improve progressive disclosure.
Remove the 'Output' section which merely restates what was already covered in the steps above, and trim the key rotation script to use actual commands rather than commented-out placeholders with echo statements.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some unnecessary elements — the post-incident review template is verbose markdown-within-markdown, the key rotation script is mostly echo statements with commented-out commands, and the Output section restates what was already covered. Some tightening is possible, but it largely avoids explaining concepts Claude already knows. | 2 / 3 |
Actionability | The skill 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 — for example, after activating emergency bypass there's no verification step to confirm it's working, and after key rotation there's no automated check that the new key is functional. For these high-risk operations, feedback loops are missing. | 2 / 3 |
Progressive Disclosure | The content is well-structured with clear headers and a logical flow, but it's a long monolithic file with no bundle files to offload detailed content. The post-incident template, session recovery endpoint code, and triage script could be split into referenced files. The reference to 'clerk-observability' at the end is a good signal but the skill itself is heavy for a single SKILL.md. | 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.