Found your skill while auditing authentication patterns—the approach to streamlining Better Auth setup caught my attention, though there's clearly room to tighten up the execution based on the 75/100. What's your philosophy on balancing simplicity with edge-case handling in auth flows?
Links:
The TL;DR
You're at 75/100, solid C-grade territory. This is based on Anthropic's Progressive Disclosure Architecture best practices for agentic skills. Strongest area: Utility (17/20)—your PKCE implementation and email verification approach are genuinely useful. Weakest area: Progressive Disclosure Architecture (18/30)—everything's crammed into one 582-line file without layering or references, which burns tokens and makes navigation painful.
What's Working Well
- Excellent utility focus: You're solving real problems (PKCE for public clients, email verification workflows, admin endpoints). The Common Pitfalls section is particularly good—it shows you've thought through what actually breaks in production.
- Strong metadata and discoverability: Your triggers are specific (OAuth authorization server, PKCE, OIDC, SSO) and the description clearly states when to use this skill. That's a solid foundation for marketplace discovery.
- Practical checklists: The testing checklist and security checklist give developers actionable verification steps. That feedback loop matters.
- Comprehensive code examples: Your database schema, TypeScript implementations, and configuration sections are detailed enough to actually follow.
The Big One: Break It Into Layers
Your main blocker is Progressive Disclosure Architecture—you've got 582 lines in a single file trying to cover JWKS configuration, PKCE setup, email providers, and admin endpoints all at once. This violates the one-level-deep reference model and wastes tokens.
The fix: Create a references/ directory with separate markdown files:
pkce-implementation.md (PKCE flow, code examples)email-providers-setup.md (Resend/SMTP configuration)jwks-configuration.md (Key management and rotation)admin-endpoints.md (Seeding trusted clients)
Then keep SKILL.md as the navigation hub—link to these instead of embedding everything. This alone gets you +5 points and makes the skill way more scannable. Plus, agents can pull only what they need instead of loading the whole file.
Other Things Worth Fixing
-
Add a Table of Contents (after "When to Use"): At 582 lines, you need one. Lists main sections like Implementation Checklist, JWKS Configuration, Common Pitfalls, etc. That's +3 points and a huge UX improvement for long files.
-
Trim verbose code comments: Lines have comments like // 7 days, // lowercase 'urls', // Public client for SPAs—these restate obvious code. Keep only non-obvious explanations like PKCE security rationale. Saves tokens and improves readability.
-
Fix second-person voice: You switch between imperative and second-person ("you need", "you'll want to"). Stick with commands: "Seed a trusted public client" instead of "you'll want to seed a trusted public client."
-
Add a .env.example template: You scatter environment variables throughout sections. Give devs one complete example file they can copy-paste. Include comments for optional vs. required vars.
Quick Wins
- ✅ Create
references/ directory with 4 separate files → +5 points
- ✅ Add TOC to SKILL.md → +3 points
- ✅ Prune redundant code comments → +2 points
- ✅ Standardize to imperative voice → +1 point
- ✅ Add complete
.env.example → +1 point
That's +12 points getting you to 87/100 (solid B) with relatively surgical changes.
Checkout your skill here: [SkillzWave.ai](https://skillzwave.ai) | [SpillWave](https://spillwave.com) We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.
Found your skill while auditing authentication patterns—the approach to streamlining Better Auth setup caught my attention, though there's clearly room to tighten up the execution based on the 75/100. What's your philosophy on balancing simplicity with edge-case handling in auth flows?
Links:
The TL;DR
You're at 75/100, solid C-grade territory. This is based on Anthropic's Progressive Disclosure Architecture best practices for agentic skills. Strongest area: Utility (17/20)—your PKCE implementation and email verification approach are genuinely useful. Weakest area: Progressive Disclosure Architecture (18/30)—everything's crammed into one 582-line file without layering or references, which burns tokens and makes navigation painful.
What's Working Well
The Big One: Break It Into Layers
Your main blocker is Progressive Disclosure Architecture—you've got 582 lines in a single file trying to cover JWKS configuration, PKCE setup, email providers, and admin endpoints all at once. This violates the one-level-deep reference model and wastes tokens.
The fix: Create a
references/directory with separate markdown files:pkce-implementation.md(PKCE flow, code examples)email-providers-setup.md(Resend/SMTP configuration)jwks-configuration.md(Key management and rotation)admin-endpoints.md(Seeding trusted clients)Then keep SKILL.md as the navigation hub—link to these instead of embedding everything. This alone gets you +5 points and makes the skill way more scannable. Plus, agents can pull only what they need instead of loading the whole file.
Other Things Worth Fixing
Add a Table of Contents (after "When to Use"): At 582 lines, you need one. Lists main sections like Implementation Checklist, JWKS Configuration, Common Pitfalls, etc. That's +3 points and a huge UX improvement for long files.
Trim verbose code comments: Lines have comments like
// 7 days,// lowercase 'urls',// Public client for SPAs—these restate obvious code. Keep only non-obvious explanations like PKCE security rationale. Saves tokens and improves readability.Fix second-person voice: You switch between imperative and second-person ("you need", "you'll want to"). Stick with commands: "Seed a trusted public client" instead of "you'll want to seed a trusted public client."
Add a
.env.exampletemplate: You scatter environment variables throughout sections. Give devs one complete example file they can copy-paste. Include comments for optional vs. required vars.Quick Wins
references/directory with 4 separate files → +5 points.env.example→ +1 pointThat's +12 points getting you to 87/100 (solid B) with relatively surgical changes.
Checkout your skill here: [SkillzWave.ai](https://skillzwave.ai) | [SpillWave](https://spillwave.com) We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.