Content
71%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 strong, highly actionable single-file skill: executable code, concrete conventions, and test commands with almost no token waste. Its main weaknesses are the inlining of ~300 lines of full module implementations that belong in reference files, and placeholder repository/secret code that keeps the scaffold from running as written.
Suggestions
Move the full per-file implementations (at minimum the Python variant and the token-blacklist details) into references/ files such as references/node-implementation.md and references/python-implementation.md, keeping SKILL.md to conventions, project structure, and key snippets with clearly signaled links.
Include the refresh-token repository implementation or a Prisma/Drizzle schema for it (and a note to load secrets from env vars) so the scaffold runs as written.
Add an ordered implementation checklist that uses the existing curl commands as explicit verify steps after each milestone (e.g., 'after wiring the controller, verify login returns an access token before adding the guard').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dominated by executable code and terse conventions ('Access tokens are stateless (verified by signature). Refresh tokens are stateful') with no padding explaining concepts Claude already knows. Minor trimmable parts — the in-memory Set blacklist toy example and the partially duplicative Python variant — keep it below a 5. | 4 / 5 |
Actionability | Provides copy-paste-ready TypeScript for service, middleware, guard, and controller plus install commands, curl tests, and a FastAPI variant. Minor gaps: 'refresh-token.repository' and 'users.repository' are imported but never defined (only a 'Replace with your actual DB queries' comment) and SECRET_KEY = "your-secret-key" is a placeholder, so the scaffold is not fully runnable as-is — matching anchor 4 rather than 5. | 4 / 5 |
Workflow Clarity | A clear implicit sequence exists (scaffold → project structure → conventions → per-file patterns → curl tests) and 'Common Commands' supplies verification steps ('Test login', 'Test authenticated request', 'Test refresh'). However there is no explicit ordered step list or 'verify before proceeding' checkpoints, placing it between anchors 3 and 4, noticeably above 3. | 4 / 5 |
Progressive Disclosure | The skill is a single well-sectioned file with no references/ directory, but roughly 300 lines of full implementations for seven modules plus a Python variant are inlined in SKILL.md. Content that clearly belongs in separate reference/template files is inline — matching anchor 3 ('content that should be separate is inline' with sections present), not 2 (structure exists) or 4 (no references and the bulk is not just 'a few key examples inline'). | 3 / 5 |
Total | 15 / 20 Passed |