API Standards Skill

.NET Detection

• *.csproj or *.sln files present
• Program.cs, Startup.cs, or appsettings.json
• ASP.NET Core or Microsoft.AspNetCore references

Python Detection

• pyproject.toml, setup.py, or requirements.txt
• FastAPI, Django, or Flask in dependencies
• main.py or app.py with router/endpoint definitions

Step 2: Read the Correct Standard

Based on the detected stack, FETCH the corresponding standard document using the WebFetch tool. Do not skip this step. Do not paraphrase from memory.

If the stack cannot be determined, ask the user which standard applies.

Step 3: Read Conditional Standards

If the task involves API versioning (version prefixes, deprecation, migration, breaking changes, or the user mentions versioning), also READ:

• https://raw.githubusercontent.com/dannypenrose/engineering-standards/main/development/api-versioning.md

If the task involves caching (Cache-Control headers, ETag, conditional requests, CDN caching, API response caching, or stale-while-revalidate), also READ:

• https://raw.githubusercontent.com/dannypenrose/engineering-standards/main/development/caching-strategy.md

Step 4: Apply Standards

With the standard document loaded, apply it naturally during API development. Do NOT lecture the user about standards or list rules unprompted. Instead:

During Endpoint Creation

• Use the correct HTTP methods and status codes per the standard
• Structure error responses in the standard format
• Apply the standard's pagination pattern for list endpoints
• Name routes and parameters following the standard's conventions
• Validate request bodies using the standard's DTO/validation approach

During Endpoint Modification

• Ensure changes maintain consistency with the standard
• If a pattern deviates from the standard, fix it or flag it
• Preserve backward compatibility unless explicitly breaking

During Code Review

• Check endpoints against the standard's requirements
• Flag deviations with specific references to what the standard prescribes
• Suggest concrete fixes, not abstract advice

Key Areas to Enforce

• Error responses: Consistent shape across all endpoints
• Pagination: Standard query parameters and response envelope
• Naming: Resource-based URLs, plural nouns, kebab-case paths
• Status codes: Correct codes for each operation type
• Validation: Request body and query parameter validation via DTOs/schemas
• Guards/Middleware: Authentication and authorization patterns per stack
• Response types: Consistent response envelope or direct returns per standard
• Versioning: If present, follows the versioning standard conventions

What NOT to Do

• Do not dump the entire standard document into the conversation
• Do not preface every action with "According to the API standards..."
• Do not refuse to write code that slightly deviates if the user has good reason
• Do not apply standards from the wrong stack (e.g., .NET patterns in a NestJS project)