nextjs-16

I looked at your nextjs-16 skill and noticed you're tackling the async component patterns that most devs still find confusing in App Router—the streaming and Suspense integration feels like it actually accounts for real-world complexity rather than glossing over it, which is probably why you landed at an 87.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 87/100, solid B territory. This skill is grounded in Anthropic's best practices for agentic skill design. Your strongest area is Progressive Disclosure Architecture (27/30)—you've got the layering right with references tucked away cleanly. Weakest spot is Spec Compliance (11/15), mostly because your description is missing trigger phrases that help agents discover and activate the skill.

What's Working Well

• Progressive Disclosure nailed it: You're not dumping everything into one massive wall of text. The SKILL.md uses ~719 lines efficiently with practical examples and clear separation into references (httpOnly-cookie-proxy.md, better-auth-integration.md). Token economy is excellent.

• Triggering is thoughtful: Your activation keywords ("pages", "layouts", "middleware", "proxy.ts", "upgrading") are specific enough that an agent knows exactly when to reach for this skill, not generic buzzwords.

• Real-world patterns over theory: You're showing actual httpOnly cookie forwarding, async params gotchas, and the migration checklist—the stuff devs actually need when upgrading, not just "here's what changed."

• Consistent terminology: "proxy" (not middleware), "async params", "cacheComponents"—you stick to the actual Next.js 16 API names, which makes it grep-friendly and reduces confusion.

The Big One: Add Trigger Phrases to Your Description

This is holding back your Spec Compliance score by 2-3 points. Right now your description reads like:

"Build Next.js 16 applications with the correct patterns. Use this skill when creating pages, layouts..."

Agents need explicit trigger phrases in the description field so they know how to invoke you. Change it to:

"Performs Next.js 16 operations. Use when asked to 'nextjs 16', 'upgrade to nextjs 16', 'nextjs 16 patterns', or 'nextjs app router'."

This small addition unlocks better discoverability in agent routing and improves your Spec Compliance from 11 to 13 points.

Other Things Worth Fixing

1. Add a table of contents (→ +1 point): A 719-line SKILL.md needs a TOC at the top. PDA guidelines say files over 100 lines should have one. Add it right after the title with links to your major sections (When to Use, Breaking Changes, Common Pitfalls, Migration Checklist).

2. Convert examples to numbered workflows (→ +2 points): Your httpOnly cookie proxy and Better Auth integration are shown as examples, but agents work better with step-by-step workflows. "1. Create catch-all route at app/api/proxy/[...path]/route.ts → 2. Import cookies from next/headers → 3. Read httpOnly token → 4. Forward with Authorization header."

3. Cut repetition in Common Pitfalls (→ +1 point): Your "Forgetting to await params" section repeats the same code you already showed in Breaking Changes #1. Link to it instead with a brief explanation of the symptom and fix.

4. Add actual error output (→ +1 point): Show the TypeScript errors and runtime output users will actually see. When they forget await params, display shows [object Promise]. When types are wrong, show the actual error message from the compiler.

Quick Wins

• Add trigger phrases to description (2-3 pts)
• TOC for the long SKILL.md (1 pt)
• Workflows over examples (2 pts)
• Cut repetition in pitfalls section (1 pt)
• Include error messages alongside code examples (1 pt)

These fixes should push you from 87 to 94-96 range. You've got the hard part down—making it discoverable and structured is just cleanup.

Checkout your skill here: SkillzWave.ai | SpillWave 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.