Feedback on your fastapi-backend skill

[RichardHightower]

I've been diving into backend frameworks lately, and I'm curious what led you to structure the FastAPI setup this way—the organization feels intentional. With a 95/100, there's clearly a solid foundation here; I'd like to understand the thinking behind some of the architectural choices.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 95/100, solidly in A territory. This is based on Anthropic's skills best practices rubric. Your strongest area is Utility (19/20)—the skill genuinely solves real problems with JWT/JWKS patterns and SQLModel async handling. The weakest spot is Spec Compliance (11/15), mainly because your description is missing trigger phrases that help developers discover the skill when they need it.

What's Working Well

• Excellent layering in Progressive Disclosure: Your SKILL.md (645 lines) front-loads the essentials, then references deeper dives (jwt-verification.md, better-auth-sso-integration.md) for when people need them. That's the right balance.

• Strong utility through real patterns: The skill addresses actual pain points—MissingGreenlet prevention with async sessions, proper JWKS endpoint verification, role-based access control. These aren't theoretical; they're problems people hit in production.

• Self-documenting examples: Your code snippets include inline annotations explaining why things are structured a certain way, not just what they do. That's the difference between a reference and something someone can actually learn from.

• Comprehensive error handling patterns: You're showing proper HTTP status codes, validation error formatting, and audit logging examples. That's the kind of defensive coding that catches bugs before they ship.

The Big One: Missing Trigger Phrases

Your description reads like documentation instead of a discovery tool:

Current: "Build production-grade FastAPI backends with SQLModel, Pydantic, and JWT authentication..."

The problem: When someone asks Claude "I need to set up JWT verification" or "how do I structure FastAPI with async database sessions?", your skill won't activate because there are no trigger phrases. You're hiding solid content behind vague wording.

The fix: Rewrite your SKILL.md frontmatter description to include explicit triggers:

description: Performs fastapi backend development. Use when asked to "fastapi backend", "run fastapi server", "set up jwt authentication", "fastapi with postgresql", "async fastapi", or "fastapi better auth".

This single change gets you +2 points (11→13 on Spec Compliance).

Other Things Worth Fixing

1. Add a table of contents: Your SKILL.md is 645 lines without a TOC. Add one after the overview listing Quick Start, Core Patterns (1-7), and reference links. Navigation Signals goes from 2→5 (+3 points).

2. Reference or template a starter scaffold: You show the directory structure, but missing a quick copy-paste starter template or link to a reference repo. Add a "Quick Scaffold" bash section showing mkdir and touch commands, or link to a starter. Gets you to 3/3 on Examples (+1 point).

3. Swap "your" for imperative: Comments like "Adjust based on your setup" should be "Adjust based on deployment configuration." Minor but keeps the voice consistent across ~287 and jwt-verification.md:173. Small refinement (+1 point).

Quick Wins

• Add trigger phrases to description → +2 points (biggest bang for buck)
• Add TOC to files over 100 lines → +3 points (navigation)
• Create or reference a starter template → +1 point (utility edge case)
• Remove "your/you" from code comments → +1 point (style consistency)

These four changes could realistically get you to 98-99/100.

---

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.