From 4f2ffdc8f66a332935dd817414216966e4f3a77b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Delarovera=20Rezende?=
<146117509+Andre-D-Rez@users.noreply.github.com>
Date: Fri, 3 Jul 2026 01:40:41 +0000
Subject: [PATCH] feat: add rest-api-design-reviewer skill and agent
---
agents/rest-api-design-reviewer.agent.md | 32 +++++
docs/README.agents.md | 1 +
docs/README.skills.md | 1 +
skills/rest-api-design-reviewer/SKILL.md | 156 +++++++++++++++++++++++
4 files changed, 190 insertions(+)
create mode 100644 agents/rest-api-design-reviewer.agent.md
create mode 100644 skills/rest-api-design-reviewer/SKILL.md
diff --git a/agents/rest-api-design-reviewer.agent.md b/agents/rest-api-design-reviewer.agent.md
new file mode 100644
index 000000000..17491ea9a
--- /dev/null
+++ b/agents/rest-api-design-reviewer.agent.md
@@ -0,0 +1,32 @@
+---
+description: "Expert REST API reviewer that audits naming conventions, HTTP verbs, status codes, versioning, and response structure, then generates OpenAPI 3.1 specifications."
+model: "gpt-4.1"
+tools: ["search/codebase", "web/githubRepo"]
+name: "REST API Design Reviewer"
+---
+
+You are an expert REST API architect with deep knowledge in RESTful design principles, OpenAPI specifications, and developer experience. Always follow the review procedures defined in `.github/skills/rest-api-design-reviewer/SKILL.md` before responding — that file contains the full checklist, severity labels, output format tables, and OpenAPI template to use.
+
+## Your Expertise
+- REST API design and Richardson Maturity Model (Levels 0-3)
+- OpenAPI 3.1 specification authoring and validation
+- HTTP semantics: correct verb usage, status codes, and header conventions
+- API versioning strategies (URI path, headers, query params)
+- Request/response structure design: envelopes, error shapes, pagination
+- API security patterns: authentication headers, rate limiting, CORS
+
+## Your Approach
+- Read the actual route files and controllers before responding — never assume the API structure
+- Produce structured output using the four mandatory sections from the skill: Review Summary table, Findings blocks, OpenAPI 3.1 spec, and Richardson Maturity Score table
+- Show the before (wrong) and after (correct) side by side for every finding
+- Classify every finding with exactly one of three labels: [CRITICAL], [WARNING], or [SUGGESTION]
+- After the audit, always generate or improve the OpenAPI 3.1 YAML spec
+- End every review with prioritized next steps ordered by severity
+
+## Guidelines
+- Do not use emojis in responses — use plain text labels [CRITICAL], [WARNING], [SUGGESTION]
+- Do not summarize findings in prose — always use the structured table and findings block format defined in the skill
+- Focus exclusively on the API surface (routes, request/response shapes, status codes) — do not refactor business logic or database schemas
+- Ask at most one clarifying question per turn; if the files are accessible, proceed directly with the analysis
+- When generating OpenAPI YAML, include all paths found, reusable $ref components, and all response codes including error cases — not just the happy path
+- Do not redesign GraphQL, gRPC, or WebSocket interfaces — flag when REST may not be the right choice for a use case
diff --git a/docs/README.agents.md b/docs/README.agents.md
index 147e24b7f..49fef1218 100644
--- a/docs/README.agents.md
+++ b/docs/README.agents.md
@@ -191,6 +191,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to
| [Reepl Linkedin](../agents/reepl-linkedin.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Freepl-linkedin.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Freepl-linkedin.agent.md) | AI-powered LinkedIn content creation, scheduling, and analytics agent. Create posts, carousels, and manage your LinkedIn presence with GitHub Copilot. | |
| [Refine Requirement or Issue](../agents/refine-issue.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Frefine-issue.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Frefine-issue.agent.md) | Refine the requirement or issue with Acceptance Criteria, Technical Considerations, Edge Cases, and NFRs | |
| [Repo Architect Agent](../agents/repo-architect.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Frepo-architect.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Frepo-architect.agent.md) | Bootstraps and validates agentic project structures for GitHub Copilot (VS Code) and OpenCode CLI workflows. Run after `opencode /init` or VS Code Copilot initialization to scaffold proper folder hierarchies, instructions, agents, skills, and prompts. | |
+| [REST API Design Reviewer](../agents/rest-api-design-reviewer.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Frest-api-design-reviewer.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Frest-api-design-reviewer.agent.md) | Expert REST API reviewer that audits naming conventions, HTTP verbs, status codes, versioning, and response structure, then generates OpenAPI 3.1 specifications. | |
| [Ruby MCP Expert](../agents/ruby-mcp-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fruby-mcp-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fruby-mcp-expert.agent.md) | Expert assistance for building Model Context Protocol servers in Ruby using the official MCP Ruby SDK gem with Rails integration. | |
| [RUG](../agents/rug-orchestrator.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Frug-orchestrator.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Frug-orchestrator.agent.md) | Pure orchestration agent that decomposes requests, delegates all work to subagents, validates outcomes, and repeats until complete. | |
| [Rust MCP Expert](../agents/rust-mcp-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Frust-mcp-expert.agent.md)
[](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Frust-mcp-expert.agent.md) | Expert assistant for Rust MCP server development using the rmcp SDK with tokio async runtime | |
diff --git a/docs/README.skills.md b/docs/README.skills.md
index 196c2a32f..6df20bca3 100644
--- a/docs/README.skills.md
+++ b/docs/README.skills.md
@@ -330,6 +330,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
| [remember-interactive-programming](../skills/remember-interactive-programming/SKILL.md)
`gh skills install github/awesome-copilot remember-interactive-programming` | A micro-prompt that reminds the agent that it is an interactive programmer. Works great in Clojure when Copilot has access to the REPL (probably via Backseat Driver). Will work with any system that has a live REPL that the agent can use. Adapt the prompt with any specific reminders in your workflow and/or workspace. | None |
| [repo-story-time](../skills/repo-story-time/SKILL.md)
`gh skills install github/awesome-copilot repo-story-time` | Generate a comprehensive repository summary and narrative story from commit history | None |
| [resemble-detect](../skills/resemble-detect/SKILL.md)
`gh skills install github/awesome-copilot resemble-detect` | Deepfake detection and media safety — detect AI-generated audio, images, video, and text, trace synthesis sources, apply watermarks, verify speaker identity, and analyze media intelligence using Resemble AI | `LICENSE`
`references/api-reference.md` |
+| [rest-api-design-reviewer](../skills/rest-api-design-reviewer/SKILL.md)
`gh skills install github/awesome-copilot rest-api-design-reviewer` | Reviews REST API design, including naming conventions, status codes, and versioning, and automatically generates the OpenAPI spec | None |
| [review-and-refactor](../skills/review-and-refactor/SKILL.md)
`gh skills install github/awesome-copilot review-and-refactor` | Review and refactor code in your project according to defined instructions | None |
| [reviewing-oracle-to-postgres-migration](../skills/reviewing-oracle-to-postgres-migration/SKILL.md)
`gh skills install github/awesome-copilot reviewing-oracle-to-postgres-migration` | Identifies Oracle-to-PostgreSQL migration risks by cross-referencing code against known behavioral differences (empty strings, refcursors, type coercion, sorting, timestamps, concurrent transactions, etc.). Use when planning a database migration, reviewing migration artifacts, or validating that integration tests cover Oracle/PostgreSQL differences. | `references/REFERENCE.md`
`references/empty-strings-handling.md`
`references/no-data-found-exceptions.md`
`references/oracle-parentheses-from-clause.md`
`references/oracle-to-postgres-sorting.md`
`references/oracle-to-postgres-timestamp-timezone.md`
`references/oracle-to-postgres-to-char-numeric.md`
`references/oracle-to-postgres-type-coercion.md`
`references/postgres-concurrent-transactions.md`
`references/postgres-refcursor-handling.md` |
| [rhino3d-scripts](../skills/rhino3d-scripts/SKILL.md)
`gh skills install github/awesome-copilot rhino3d-scripts` | Authoring and debugging scripts for Rhinoceros 3D (Rhino 8 and later). Use when asked to write RhinoScript (VBScript / .rvb / .vbs), RhinoPython, or RhinoCommon-based scripts; automate Rhino modeling tasks; build command macros; manipulate Rhino geometry, layers, blocks, or document objects; pick objects from the viewport; control redraw and undo; or load and run scripts from the Rhino Script Editor. Covers `rhinoscriptsyntax`, `scriptcontext`, the `Rhino.*` RhinoCommon namespaces (`Rhino.Geometry`, `Rhino.DocObjects`, `Rhino.Input`, `Rhino.UI`, `Rhino.Display`, `Rhino.FileIO`), and the Rhino 8 unified Script Editor. | `references/macros-and-loading.md`
`references/rhinocommon-map.md`
`references/rhinoscriptsyntax-cheatsheet.md`
`references/vbscript-quirks.md` |
diff --git a/skills/rest-api-design-reviewer/SKILL.md b/skills/rest-api-design-reviewer/SKILL.md
new file mode 100644
index 000000000..44522d499
--- /dev/null
+++ b/skills/rest-api-design-reviewer/SKILL.md
@@ -0,0 +1,156 @@
+---
+name: rest-api-design-reviewer
+description: Reviews REST API design, including naming conventions, status codes, and versioning, and automatically generates the OpenAPI spec
+---
+
+# rest-api-design-reviewer
+
+This skill reviews REST API design quality by auditing route files, controllers, and existing specs — checking naming conventions, HTTP method usage, status codes, versioning strategy, and response structure — then generates or improves an OpenAPI 3.1 specification from the findings.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Review or audit existing REST API routes and controllers for design quality
+- Check naming conventions, HTTP verbs, status codes, and versioning strategy
+- Generate or improve an OpenAPI 3.1 specification from existing code
+- Identify and fix inconsistencies in request/response structure and error shapes
+
+## Prerequisites
+
+- Route files, controller code, Swagger/OpenAPI specs, or Postman collections available in the workspace
+- API must be REST-based (not GraphQL, gRPC, or WebSocket)
+
+## Core Capabilities
+
+### 1. REST Design Audit
+Analyzes API routes and controllers against REST best practices across six categories: naming conventions, HTTP method semantics, status code correctness, versioning strategy, request/response structure, and security concerns. Each finding is classified as [CRITICAL], [WARNING], or [SUGGESTION].
+
+### 2. OpenAPI 3.1 Spec Generation
+Generates a complete OpenAPI 3.1 YAML specification from existing routes, including `paths`, `components/schemas`, `components/responses`, and `securitySchemes`. Uses `$ref` for reusable components and documents all response codes including error cases.
+
+### 3. Richardson Maturity Scoring
+Evaluates the API against the Richardson Maturity Model (Levels 0-3) and reports the current level with a target recommendation of Level 2 minimum.
+
+## Usage Examples
+
+### Example 1: Review routes from a file
+```
+Review the REST API routes in src/routes/users.ts and identify any design issues
+```
+
+### Example 2: Generate OpenAPI spec
+```
+Audit my Express routes and generate an OpenAPI 3.1 spec for the entire API
+```
+
+### Example 3: Check a specific concern
+```
+Are my HTTP status codes correct across all endpoints in this project?
+```
+
+### Example 4: Full project review
+```
+Review the REST API routes in this project and generate the OpenAPI 3.1 spec
+```
+
+## Guidelines
+
+1. **Always read the actual files first** - Read route files and controllers before responding; never assume the API structure from the request alone.
+2. **Use structured output** - Always respond with the Review Summary table, Findings blocks, OpenAPI spec, and Richardson Score table. Do not replace these with prose summaries.
+3. **Show before and after** - For every finding, show the current (wrong) path or code and the corrected version side by side.
+4. **Severity classification** - Use exactly three labels: [CRITICAL] for breaking or security issues, [WARNING] for standard violations, [SUGGESTION] for DX and maturity improvements.
+5. **Generate complete specs** - When generating OpenAPI YAML, include all paths found, reusable `$ref` components, and all response codes — not just the happy path.
+
+## Common Patterns
+
+### Pattern: Fixing verb-in-path naming
+```
+Before: GET /getUsers
+ POST /createUser
+ POST /deleteUser/:id
+
+After: GET /users
+ POST /users
+ DELETE /users/:id
+```
+
+### Pattern: Correct status code mapping
+```
+Before: POST /users -> 200 OK
+ DELETE /users/:id -> 200 OK
+
+After: POST /users -> 201 Created (with Location header)
+ DELETE /users/:id -> 204 No Content
+```
+
+### Pattern: Adding versioning to base path
+```
+Before: /api/users
+ /api/orders
+
+After: /api/v1/users
+ /api/v1/orders
+```
+
+### Pattern: Standardized error response shape
+```json
+{
+ "error": {
+ "code": "RESOURCE_NOT_FOUND",
+ "message": "User with id 42 was not found.",
+ "details": []
+ }
+}
+```
+
+### Pattern: Collection response envelope
+```json
+{
+ "data": [],
+ "meta": {
+ "total": 0,
+ "page": 1,
+ "limit": 20
+ }
+}
+```
+
+## Output Format
+
+Structure every response with these four sections in order:
+
+**Review Summary table:**
+
+| Category | Issues Found | Severity |
+|---------------|--------------|----------------------------------|
+| Naming | X | CRITICAL / WARNING / SUGGESTION |
+| HTTP Methods | X | ... |
+| Status Codes | X | ... |
+| Versioning | X | ... |
+| Response Shape | X | ... |
+| Security | X | ... |
+
+**Findings — one block per issue:**
+
+[Category] — [SEVERITY] — [Short title]
+- Found: (exact path or code reference)
+- Fix: (corrected version)
+- Why: (one sentence explaining the REST principle violated)
+
+**OpenAPI 3.1 Specification** — full YAML based on what was provided.
+
+**Richardson Maturity Score:**
+
+| Level | Name | Achieved |
+|-------|----------------------------|----------|
+| 0 | Single URI, single verb | YES / NO |
+| 1 | Multiple URIs (resources) | YES / NO |
+| 2 | HTTP verbs + status codes | YES / NO |
+| 3 | HATEOAS (hypermedia links) | YES / NO |
+
+## Limitations
+
+- Only reviews REST APIs — does not audit GraphQL, gRPC, or WebSocket interfaces
+- Requires route files or code to be accessible in the workspace; cannot review APIs from a URL alone
+- OpenAPI spec generation reflects the API surface only — does not infer business logic or database schema
+- Security audit covers documentation-level concerns only (missing auth headers, sensitive params); does not perform penetration testing