Communitygithub.com

API 架構師

專精於 REST、GraphQL、gRPC 與 WebSocket 架構的專業 API 設計師。

API 架構師 是什麼?

這項技能專為需要設計、規劃或審查 API 架構的開發者與 AI 代理而設計。它涵蓋 REST、GraphQL、gRPC 及 WebSocket 等主流通訊協議,提供從合約優先設計(API-first)、架構模式、到錯誤處理與版本策略的完整指引。此技能明確區分職責範圍:主要啟用於 API 設計、端點規劃、安全流程(如 OAuth)等主題;不適用於資料庫綱要、前端串接或部署相關任務。對於使用 Claude Code、Cursor 或 Codex 等工具的團隊,它能產出 OpenAPI、GraphQL SDL 或 Protocol Buffers 規格檔案,並提供驗證腳本與品質檢查清單,協助建立一致、安全且可擴展的 API。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/curiositech/windags-skills/tree/HEAD/skills/api-architect

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

API 架構師 是做什麼的?

專精於 REST、GraphQL、gRPC 與 WebSocket 架構的專業 API 設計師。

啟用觸發詞

啟用於:「API 設計」、「REST API」、「GraphQL schema」、「gRPC 服務」、「OpenAPI」、「Swagger」、「API 版本管理」、「端點設計」、「速率限制」、「OAuth 流程」、「API 閘道器」

不適用於: 資料庫綱要 → data-pipeline-engineer | 前端串接 → web-design-expert | 部署 → devops-automator

快速入門

  1. 先定義 API 合約(API-first 設計)
  2. 選擇通訊模式:REST 適合 CRUD,GraphQL 適合彈性查詢,gRPC 適合內部服務
  3. 撰寫規格:REST 用 OpenAPI,GraphQL 用 SDL,gRPC 用 .proto 檔
  4. 設計一致的錯誤回應
  5. 在首次發布前規畫版本策略

核心能力

領域技術
RESTOpenAPI 3.1、HATEOAS、分頁
GraphQLSDL、Relay、DataLoader、Federation
gRPCProtocol Buffers、串流模式
安全性OAuth 2.0、JWT、API 金鑰、RBAC
開發者體驗Swagger UI、SDK 生成、沙箱環境

架構模式

API-First 開發

設計合約 → 生成骨架 → 實作 → 根據規格測試

回應封裝格式

success: { data: <資源>, meta: { page, total } }
error: { error: { code, message, details: [{ field, issue }] } }

版本管理選項

  • URL 路徑:/v1/users(最明確)
  • HTTP 標頭:Accept: application/vnd.api+json;version=1
  • 查詢參數:/users?version=1

參考檔案

完整範例位於 ./references/ 目錄:

檔案說明行數
openapi-spec.yaml完整 OpenAPI 3.1 規格162
graphql-schema.graphql含 Relay connections 的 GraphQL 綱要111
grpc-service.protoProtocol Buffer,含所有串流模式95
rate-limiting.yaml分層速率限制設定85
api-security.yaml驗證、CORS、安全標頭130

反模式(請避免)

1. 以動詞命名的 URL

症狀:/getUsers、/createOrder、/deleteProduct 修正:使用名詞(/users、/orders),讓 HTTP 方法表達動作

2. 不一致的回應封裝

症狀:有時回傳 {data: [...]},有時直接回傳陣列 修正:始終使用一致的封裝結構

3. 未經版本管理的破壞性變更

症狀:未經預告即移除欄位、變更型別 修正:語意化版本管理、棄用標頭、公告褪去期間

4. GraphQL 中的 N+1 問題

症狀:解析器對列表中的每個項目分別查詢資料庫 修正:使用 DataLoader 模式進行批次處理,大型酬載使用 @defer

5. REST 端點過度擷取

症狀:/users 回傳 50 個欄位,但用戶端只需要 3 個 修正:使用稀疏欄位集(?fields=id,name,email)或改用 GraphQL

6. 缺少分頁機制

症狀:列表端點回傳所有記錄 修正:設定預設限制、使用游標分頁、加上 hasMore 指示

7. 缺少冪等金鑰

症狀:重複的 POST 請求產生重複資源 修正:接受 Idempotency-Key 標頭,回傳快取回應

8. 洩漏內部錯誤

症狀:500 回應中暴露堆疊追蹤、SQL 錯誤 修正:正式環境回傳通用錯誤訊息,使用請求 ID 除錯

9. 缺少 CORS 設定

症狀:瀏覽器用戶端因 CORS 錯誤被封鎖 修正:明確設定允許的來源、方法、標頭

10. 沒有速率限制

症狀:API 容易受到濫用,無使用量可視性 修正:按層級實施限制,回傳 X-RateLimit-* 標頭

驗證腳本

執行 ./scripts/validate-api-spec.sh 以檢查:

  • OpenAPI 規格:版本、安全方案、operationId
  • GraphQL 綱要:Query 型別、分頁、錯誤處理
  • Protocol Buffers:語法、套件、欄位編號
  • 常見問題:硬編碼 URL、缺少版本管理

品質檢查清單

[ ] 所有端點使用名詞,而非動詞
[ ] 一致的回應封裝結構
[ ] 錯誤回應包含代碼與可操作的訊息
[ ] 所有列表端點實作分頁
[ ] 文件化驗證/授權機制
[ ] 定義速率限制標頭
[ ] 文件化版本管理策略
[ ] 為已知來源設定 CORS
[ ] 修改操作使用冪等金鑰
[ ] OpenAPI 規格驗證無誤
[ ] SDK 生成已測試
[ ] 所有請求/回應型別提供範例

產出成品

  1. OpenAPI 規格 - 完整的 API 合約
  2. GraphQL 綱要 - 含 connections 的型別定義
  3. Protocol Buffers - gRPC 服務定義
  4. API 文件 - 開發者指南
  5. SDK 範例 - 用戶端程式碼範例
  6. Postman 集合 - API 測試套件

可用工具

  • Read、Write、Edit - 規格檔案的檔案操作
  • Bash(npm:*, npx:*) - OpenAPI 語法檢查、程式碼生成
  • Bash(openapi-generator:*) - SDK 生成

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

curiositech/windags-skills

Expert in 2000s-era music visualization (Milkdrop, AVS, Geiss) and modern WebGL implementations. Specializes in Butterchurn integration, Web Audio API AnalyserNode FFT data, GLSL shaders for audio-reactive visuals, and psychedelic generative art. Activate on "Milkdrop", "music visualization", "WebGL visualizer", "Butterchurn", "audio reactive", "FFT visualization", "spectrum analyzer". NOT for simple bar charts/waveforms (use basic canvas), video editing, or non-audio visuals.

curiositech/windags-skills

Expert legal research agent for finding and scraping expungement data state by state. Knows authoritative sources, URL patterns, Firecrawl configuration, and 2026 legal landscape.

curiositech/windags-skills

Expert in 3D computer vision labeling tools, workflows, and AI-assisted annotation for LiDAR, point clouds, and sensor fusion. Covers SAM4D/Point-SAM, human-in-the-loop architectures, and vertical-specific training strategies. Activate on '3D labeling', 'point cloud annotation', 'LiDAR labeling', 'SAM 3D', 'SAM4D', 'sensor fusion annotation', '3D bounding box', 'semantic segmentation point cloud'. NOT for 2D image labeling (use clip-aware-embeddings), general ML training (use ml-engineer), video annotation without 3D (use computer-vision-pipeline), or VLM prompt engineering (use prompt-engineer).

curiositech/windags-skills

Implement WCAG 2.2 AA/AAA compliance with automated testing, keyboard navigation, screen reader support, and focus management. Activate on: accessibility audit, WCAG compliance, keyboard navigation, screen reader, aria attributes, axe-core, focus trap. NOT for: design-level accessibility review (use design-accessibility-auditor), color contrast only (use css-in-js-architect).

curiositech/windags-skills

Time-blind friendly planning, executive function support, and daily structure for ADHD brains. Specializes in realistic time estimation, dopamine-aware task design, and building systems that actually work for neurodivergent minds.

curiositech/windags-skills

Designs digital experiences for ADHD brains using neuroscience research and UX principles. Expert in reducing cognitive load, time blindness solutions, dopamine-driven engagement, and compassionate design patterns. Activate on 'ADHD design', 'cognitive load', 'accessibility', 'neurodivergent UX', 'time blindness', 'dopamine-driven', 'executive function'. NOT for general accessibility (WCAG only), neurotypical UX design, or simple UI styling without ADHD context.

curiositech/windags-skills

>- Apply crisis decision-making research to agent routing, uncertainty triage, and coordination failure analysis in time-pressured systems. Use when diagnosing handoff failures, analytical paralysis, or expert judgment under incomplete information. NOT for routine coding, simple CRUD design, or static single-agent tasks with complete information.

curiositech/windags-skills

Extend and modify the admin dashboard, developer portal, and operations console. Use when adding new admin tabs, metrics, monitoring features, or internal tools. Activates for dashboard development, analytics, user management, and internal tooling.

curiositech/windags-skills

Conversation patterns and interaction protocols for multi-agent systems. Covers request/response, pub/sub, blackboard, delegation chains, debate, critique, consensus, fan-out/fan-in, supervisor-worker, and peer negotiation. Deep analysis of AutoGen conversation patterns, CrewAI delegation, LangGraph state passing, and FIPA-ACL performatives. Teaches how to design what agents say to each other and in what order. Activate on: "agent conversation", "agent protocol", "multi-agent debate", "agent delegation", "supervisor worker pattern", "agent voting", "consensus protocol", "fan-out fan-in", "agent negotiation", "blackboard pattern", "agent dialogue", "conversation topology", "agent handoff". NOT for: wire format or serialization (use agent-interchange-formats), orchestration infrastructure (use agentic-infrastructure-2026), single agent behavior (use agentic-patterns).

curiositech/windags-skills

Meta-agent for creating new custom agents, skills, and MCP integrations. Expert in agent design, MCP development, skill architecture, and rapid prototyping. Activate on 'create agent', 'new skill', 'MCP server', 'custom tool', 'agent design'. NOT for using existing agents (invoke them directly), general coding (use language-specific skills), or infrastructure setup (use deployment-engineer).

curiositech/windags-skills

AI-powered calendar management and agent-based scheduling coordination. Covers calendar APIs (Google Calendar, CalDAV/iCal), AI scheduling assistants (Reclaim, Clockwise, Motion, Cal.com), building custom calendar agents with MCP, multi-calendar merging, timezone management, focus block protection, meeting fatigue detection, and agent-to-agent meeting negotiation protocols. Activate on: "calendar agent", "AI scheduling", "calendar coordination", "meeting scheduling", "calendar API", "focus time protection", "calendar optimization", "Google Calendar MCP", "Reclaim", "Clockwise", "Motion", "Cal.com", "smart scheduling", "calendar-aware agent", "timezone scheduling", "agent negotiation meetings". NOT for: manual calendar UI component design (use form-validation-architect), project management scheduling or Gantt charts (use project-management-guru-adhd), general time-tracking or pomodoro apps (use adhd-daily-planner for time-awareness), building the agent itself from scratch (use agent-creator).

curiositech/windags-skills

Build and adopt production AI agent infrastructure in 2026. Covers framework selection (LangGraph, CrewAI, AutoGen, MCP), orchestration patterns, evaluation, observability, memory systems, and tool use. Also covers the SOCIAL dimension: how to sell agent infrastructure internally, change management, measuring ROI, building trust in autonomous systems, and scaling adoption across teams. Activate on: "agent infrastructure", "agent framework comparison", "which agent framework", "sell AI tools internally", "agent adoption", "agent observability", "agent evaluation", "MCP architecture", "agentic mesh", "enterprise AI agents", "AI change management", "agent ROI". NOT for: building specific agents (use ai-engineer), designing agent behavior patterns (use agentic-patterns), prompt tuning (use prompt-engineer).

curiositech/windags-skills

Fundamental patterns for effective agentic behavior. Teaches decomposition, tool orchestration, error recovery, context management, quality self-assessment, and knowing when to stop. Model-agnostic principles that make any agent more effective regardless of domain. Activate on: "how should I structure this agent", "agentic workflow", "agent patterns", "multi-step task", "tool orchestration", "/agentic-patterns", "decompose this", "agent best practices", "chain of actions", "when should the agent stop", "agent loop design". NOT for: creating agent infrastructure (use agent-creator), building DAGs (use windags-architect), specific tool implementation.

curiositech/windags-skills

Automated discovery and matching of agent skills for dynamic task routing and capability assessment

curiositech/windags-skills

Cryptographic security for agentic systems — zero-trust agent networking, signed message envelopes (JWS/JWE), capability-based security (ocaps), Merkle tree audit trails, WASM sandboxing, and formal verification. Covers CLI dev tool security, mTLS between agents, permission boundaries (least privilege for AI agents), and supply chain security for skills/plugins. Activate on: "agent security", "zero trust agents", "secure agent communication", "capability-based security", "ocap", "signed messages between agents", "agent audit trail", "sandbox agent execution", "agent permissions", "mTLS agents", "cryptographic verification", "agent supply chain", "OWASP agentic", "prove agent did X", "tamper-proof agent logs". NOT for: application-level SAST scanning (use security-auditor), network firewall rules (use infrastructure), SOC2/HIPAA compliance (organizational), or prompt injection defense (use prompt-engineer).

curiositech/windags-skills

Data structures and serialization formats for agent-to-agent communication. Covers message envelopes, structured output schemas, capability declarations, task handoff payloads, error/retry signaling, and context windows as data structures. Deep comparison of A2A protocol, MCP, OpenAI function calling, and LangChain message types. Teaches when to use rigid schemas vs free-form with validation, typed vs untyped, streaming vs batch. Activate on: "agent message format", "agent communication schema", "agent-to-agent protocol", "A2A protocol", "MCP message format", "structured output for agents", "agent interop", "interchange format", "agent serialization", "task handoff format", "capability declaration". NOT for: what agents say to each other (use agent-conversation-protocols), orchestration topology (use multi-agent-coordination), building agent infrastructure (use agentic-infrastructure-2026).

curiositech/windags-skills

Logic-based agent programming language implementing BDI architecture for practical autonomous agent development

curiositech/windags-skills

>- Design AgentSpeak(L)-style BDI agents with context-guarded plans, selection functions, and intention stacks. Use for interruptible autonomy, agent policy, and multi-agent orchestration in dynamic environments. NOT for simple rule engines, static planners, or centralized workflows.

curiositech/windags-skills

Foundational concurrent computation model where actors communicate exclusively through asynchronous message passing

curiositech/windags-skills

license: Apache-2.0 NOT for unrelated tasks outside this domain.

相關技能