feat: add rest-api-design-reviewer skill and agent

[Andre-D-Rez]

Pull Request Checklist

• I have read and followed the CONTRIBUTING.md guidelines.
• I have read and followed the Guidance for submissions involving paid services.
• My contribution adds a new instruction, prompt, agent, skill, workflow, or canvas extension file in the correct directory.
• The file follows the required naming convention.
• The content is clearly structured and follows the example format.
• I have tested my instructions, prompt, agent, skill, workflow, or canvas extension with GitHub Copilot.
• I have run npm start and verified that README.md is up to date.
• I am targeting the main branch for this pull request.

---

Description

Adds a REST API Design Reviewer skill and agent that audits REST API design quality and generates OpenAPI 3.1 specifications from existing routes and controllers.

The skill activates automatically when the user asks to review, audit, or improve a REST API. It runs a structured check across six categories: naming conventions (plural nouns, no verbs in paths, kebab-case), HTTP method semantics (correct use of GET/POST/PUT/PATCH/DELETE), status code correctness (201 on creation, 204 on delete, 422 on validation errors), versioning strategy (explicit /api/v1/ prefix), response envelope consistency (data/meta structure, standardized error shape), and security concerns (auth headers, sensitive query params, rate limiting documentation). Every finding is classified as [CRITICAL], [WARNING], or [SUGGESTION] with a concrete before/after fix and a one-line explanation of the REST principle violated. The output always closes with a full OpenAPI 3.1 YAML specification and a Richardson Maturity Model score (Levels 0–3).

The agent provides a Senior REST API Architect persona. Before responding, it reads the actual route files and controllers in the workspace rather than assuming the API structure. It then follows the skill's review procedures to produce the same structured output: Review Summary table, Findings blocks, OpenAPI 3.1 spec, and Richardson Score, and ends every session with a prioritized action list ordered by severity.

The two work together because the agent handles the behavior (reading files, assuming the architect persona, deciding what to investigate) while the skill defines the procedure (what to check, how to classify findings, what format to output). The agent explicitly references the skill file before responding, so activating the agent automatically brings the full skill checklist into every review session.

---

Type of Contribution

• New instruction file.
• New prompt file.
• New agent file.
• New plugin.
• New skill file.
• New agentic workflow.
• New canvas extension.
• Update to existing instruction, prompt, agent, plugin, skill, workflow, or canvas extension.
• Other (please specify):

---

Additional Notes

The skill and agent work together: the agent references the skill's procedures to ensure consistent structured output across sessions.

---

By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.

[github-actions]

🔒 PR Risk Scan Results

Scanned 4 changed file(s).

Severity	Count
🔴 High	0
🟠 Medium	1
ℹ️ Info	0

Severity	Rule	File	Line	Match
🟠	package-exec-command	docs/README.skills.md	31	| [acreadiness-assess](../skills/acreadiness-assess/SKILL.md)<br />`gh skills install github/awesome-copilot acreadiness-assess` | Run the AgentRC readiness assessment on the curre

This is an automated soft-gate report. Findings indicate review targets and do not block merge by themselves.

[github-actions]

🔍 Vally Lint Results

⚠️ Warnings or advisories found

Scope	Checked
Skills	1
Agents	1
Total	2

Severity	Count
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	1

Summary

Level	Finding
ℹ️	Vally currently lints SKILL.md content. Agent files were detected but skipped:

Full linter output

### Linting skills/rest-api-design-reviewer
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: 'commander@15.0.0',
npm warn EBADENGINE   required: { node: '>=22.12.0' },
npm warn EBADENGINE   current: { node: 'v20.20.2', npm: '10.8.2' }
npm warn EBADENGINE }
npm warn deprecated prebuild-install@7.1.3: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
✅ rest-api-design-reviewer (2/2 checks passed)
    ✓ [spec-compliance] All 1 skill(s) are spec-compliant.
        ✓ spec-compliance: All spec checks passed.
    ✓ [valid-refs] All file references across 1 skill(s) are valid.
        ✓ valid-refs: All file references resolve to existing files within the skill directory.

1 skill(s) linted, 1 passed

### Agent files detected (not linted by vally)
ℹ️ Vally currently lints SKILL.md content. Agent files were detected but skipped:
agents/rest-api-design-reviewer.agent.md

[Copilot]

Pull request overview

Adds a new REST API Design Reviewer capability to the awesome-copilot catalog by introducing a skill (procedure/checklist) and a companion agent (persona + execution approach), and registering both in the generated docs indexes.

Changes:

• Added rest-api-design-reviewer skill with REST audit criteria and OpenAPI 3.1 generation instructions.
• Added REST API Design Reviewer agent definition intended to apply the skill’s structured review format.
• Updated skills and agents documentation indexes to include the new entries.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
skills/rest-api-design-reviewer/SKILL.md	New skill defining the REST audit checklist and required output format.
agents/rest-api-design-reviewer.agent.md	New agent persona/behavior intended to follow the skill’s procedure.
docs/README.skills.md	Registers the new skill in the skills index.
docs/README.agents.md	Registers the new agent in the agents index.