Skip to content

feat(skills): add api-design skill and plugin manifest - #17

Merged
ms-shashank merged 1 commit into
Oxcode-ai:mainfrom
h30s:feat/api-design-skill
Aug 31, 2026
Merged

feat(skills): add api-design skill and plugin manifest#17
ms-shashank merged 1 commit into
Oxcode-ai:mainfrom
h30s:feat/api-design-skill

Conversation

@h30s

@h30s h30s commented Aug 26, 2026

Copy link
Copy Markdown
Member

Closes #9

Summary

Adds the api-design skill to review public interfaces (HTTP/REST endpoints, GraphQL schemas, RPC methods, SDK functions, and exported module types) before they become expensive breaking changes after release.

PR Requirements Checklist (per CONTRIBUTING.md)

1. Task Tested & Before vs. After

  • Task: Reviewing a newly added POST /api/v1/transfers endpoint and a GET /api/v1/transfers list endpoint.

  • Before (Default model review):

    • Focused on internal helper style.
    • Suggested generic code comments.
    • Accepted the flat array return.
    • Accepted the lack of idempotency keys without identifying post-release migration costs.
  • After (With /api-design):

    • Flagged the omission of an idempotency key mechanism on state mutation, noting that requiring it post-release is a breaking change for client integrations.
    • Flagged the unpaginated array return shape, calculating the post-release cost: wrapping the array in an object envelope breaks JSON deserializers across all clients.
    • Verified caller code in apps/web and services/worker, grounding all findings in concrete caller impact.
    • Explicitly separated contract defects from naming preferences.

2. What was Deliberately Left Out (and Why)

  • Internal implementation reviews: Omitted critiques of internal helper functions, local algorithms, and database queries because private implementation can be refactored at any time without breaking downstream callers.

  • Speculative protocol additions: Omitted generic suggestions for alternative architectures (e.g. gRPC/WebSockets) to avoid noise and focus strictly on the interface contract at hand.

  • Linter/formatting nits: Delegated formatting and syntax styling to automated formatters.

3. Tools Matching

  • Configured with tools: chat (read-only) because interface review is a pure evaluation task that does not mutate files or execute commands.

@h30s
h30s requested a review from ms-shashank August 26, 2026 10:38
@ms-shashank
ms-shashank force-pushed the feat/api-design-skill branch from bb0233d to ffc138c Compare August 31, 2026 08:06
@ms-shashank
ms-shashank merged commit 41742d7 into Oxcode-ai:main Aug 31, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

New skill: api-design, review the interface before it is expensive to change

2 participants