Content
63%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A dense, highly project-specific architecture reference with strong actionable detail (code contracts, file paths, error-handling tables, pitfalls) but weak progressive disclosure: it is a single ~615-line monolith with no references/ files, and it repeats several invariants, including one internal contradiction about the cookie client's WebSocket capability. Splitting contract/type listings into references and deduplicating repeated rules would lift both conciseness and organization.
Suggestions
Move the full type and contract listings (AuthClient, Connection, AuthState, PersistedAuth/OAuthTokenGrant, PersistedAuthStorage, the Better Auth plugin config) into references/ files (e.g. references/contracts.md), keeping one-line summaries in SKILL.md and well-signaled links.
Deduplicate repeated invariants: the connection.status liveness rule appears in 'Current Model', 'Public Surface' (twice), and 'Common Pitfalls'; state each rule once in its owning section and reference it elsewhere.
Resolve the internal contradiction about createSameOriginCookieAuth: one section says it 'has openWebSocket like every client and denies permanently' while the Server Routes section says it is 'a plain AuthClient (no openWebSocket)' — pick one description of the contract.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and almost entirely project-specific (ADRs, invariants, close-code contracts) so it is not padded with things Claude already knows, but key facts are repeated: the connection.status live-machine rule appears three times, the reload-gate rules twice, and the network-gate fail-closed invariant is restated across sections. This is 'mostly efficient but could be tightened' — not the anchor-2 pattern of unnecessary generic explanation, but clearly above it. | 3 / 5 |
Actionability | Concrete, copy-shaped guidance throughout: factory signatures (createOAuthAppAuth({ baseURL, clientId, launcher, persistedAuthStorage })), real file paths (bearer-fetch.ts, require-auth.ts, reload-on-auth-change.ts), full type contracts, an explicit 401-vs-503 error-action table, and a 15-item do/don't pitfalls list. A few blocks are illustrative only (the Hono composition txt diagram), and one contradiction — the cookie client is described as having openWebSocket 'like every client and denies permanently' in one section and as 'a plain AuthClient (no openWebSocket)' in another — keeps it below fully-executable anchor 5. | 4 / 5 |
Workflow Clarity | This is an architecture/reference skill rather than a stepwise procedure, but its state machines are laid out with explicit failure branches and checkpoints: the network-gate decision table (unverified -> /api/session -> verified/pause/fail-closed), the sign-in launcher outcomes ('launched' vs 'completed'), and the WS close-code / HTTP status classification with the client action for each. Not quite the anchor-5 pattern of validate-fix-retry feedback loops, and no destructive/batch operations requiring validation caps. | 4 / 5 |
Progressive Disclosure | Section headers are well organized (Upstream Grounding, Current Model, Public Surface, Persisted Cell, Network Gate, Transport, Boot selection, Pitfalls), but there are no bundle files at all: everything, including full type/contract listings (AuthClient, PersistedAuth, PersistedAuthStorage) and the complete Better Auth plugin config, is inlined in a ~615-line SKILL.md. Content that clearly belongs in references/ files is inline, which is the anchor-3 pattern ('some structure but could be better organized; content that should be separate is inline'). | 3 / 5 |
Total | 14 / 20 Passed |