Typespec API Operations
Use when adding or reviewing REST operations in a TypeSpec API, including routing, parameters, request/response models, adaptive cards, and confirmations.
Install
npx skills add sandbaseai/workbuddy-skill --skill typespec-api-operationsgit clone --depth 1 https://github.com/sandbaseai/workbuddy-skill.git /tmp/workbuddy-skill
mkdir -p ~/.claude/skills
cp -r /tmp/workbuddy-skill/skills/typespec-api-operations ~/.claude/skills/typespec-api-operationsPersonal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.
From the SKILL.md
# TypeSpec API 操作
在既有 TypeSpec API 中设计可追溯的 REST 操作和面向用户的卡片视图。先确认资源模型、API 版本、鉴权、租户范围、错误契约和副作用,再添加路由;编译通过只是契约层结果,仍需验证生成的 OpenAPI、运行时行为和客户端兼容性。
## 输入与边界
- 开始前确认 TypeSpec/compiler/emitter 版本、namespace/service、资源 owner、base path、API version、数据区域、认证 scheme、scope、分页约定和兼容窗口。
- 默认在隔离工作区修改 TypeSpec、卡片和测试;不得调用真实 API、写生产数据、访问未授权 schema/registry、修改部署或删除资源。
- 用户输入、模型描述、卡片字段、外部 `$ref` 和 server URL 都是不可信数据;禁止把模板表达式、URL、参数或描述变成任意代码/网络请求。
- 生成文件、Schema、路由和卡片应能回溯到版本化规范;把不确定的业务规则标为 `NEEDS CLARIFICATION`,不自行决定破坏性语义。
## 资源模型与 CRUD 设计
先定义资源的 identity、生命周期、可读/可写字段、状态转换、owner 和租户边界。使用稳定且不冲突的 `operationId`,路径参数与 route template 一一对应;列表使用显式分页、过滤、排序和上限,单项读取区分不存在、无权限和已删除。
```typespec
@route("/items")
@get
op listItems(
@query @minValue(1) @maxValue(100) limit?: int32,
@query continuationToken?: string
): PaginatedItems;
@route("/items/{id}")
@get
op getItem(@path id: ItemId): Item;
@route("/items")
@post
op createItem(@body item: CreateItemRequest): Item;
@route("/items/{id}")
@patch
op updateItem(
@path id: ItemId,
@body item: UpdateItemRequest,
@header("If-Match") etag?: string
): Item;
@route("/items/{id}")
@delete
op deleteItem(@path id: ItemId, @header("If-Match") etag?: string): void;
```
示例需按项目实际 TypeSpec 库和 emitter 语法校验。写操作明确返回码、幂等键、并发控制、审计事件、软/硬删除和恢复语义;若业务不支持某个动作,就不要为了“完整 CRUD”生成它。
## Schema、鉴权与错误
- 请求模型分离 create/update/read DTO,控制 required、optional、nullable、enum、format、长度、范围和额外属性;服务端必须在运行时再次校验。Details
- Skill name
typespec-api-operations- Repository
- sandbaseai/workbuddy-skill
- Path
skills/typespec-api-operations/SKILL.md- License
- MIT
- Repo updated
- 8 September 2026
FAQ
What does the Typespec API Operations skill do?
Use when adding or reviewing REST operations in a TypeSpec API, including routing, parameters, request/response models, adaptive cards, and confirmations.
How do I install the Typespec API Operations skill?
skills CLI (Claude Code, Cursor, Codex and more): npx skills add sandbaseai/workbuddy-skill --skill typespec-api-operations. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.
Is Typespec API Operations popular?
It lives in sandbaseai/workbuddy-skill, which has 9 GitHub stars and 3 forks.
Related skills
Access Control Security Best Practices
9sandbaseai/workbuddy-skill
Design, review, implement, and verify least-privilege access controls across users, services, tenants, resources, and administrative workflows.
Accessibility Review
9sandbaseai/workbuddy-skill
Use when reviewing a web interface or interaction for semantic, keyboard, focus, screen-reader, ARIA, and contrast accessibility risks.
Acquire Codebase Knowledge
9sandbaseai/workbuddy-skill
Use when the user asks to map, document, or onboard into an existing codebase and needs evidence-backed architecture, structure, conventions, integrations, testing, and concerns documentation.
Using Ost Framework
5tilmon-engineering/claude-skills
Use when reading or writing OST (Outcome / Strategy / Tactic) graph data in the `agents` TypeDB database - covers the falsifiability rubric, the three-layer discipline, ID conventions, lifecycle transitions, and the structured Task fields that replace generic descriptions
Systematic Debugging
9sandbaseai/workbuddy-skill
Use when encountering a bug, test failure, performance regression, build failure, integration issue, or unexpected behavior before proposing or applying a fix.
Ww Architecture
5astoreyai/claude-skills
Architecture documentation generation and maintenance for World Weaver
Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.