[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6FEEN4P6XAVHH02YABBY1DY":3,"skill-same:01M6FEEN4P6XAVHH02YABBY1DY":45},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":20,"frontMatter":21,"refName":22,"commitSha":23,"skillDirectory":24,"forksCount":25,"repositoryHtmlUrl":26,"repositoryHomepageUrl":27,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":29,"updatedAt":30,"install":31,"resources":44},"01M6FEEN4P6XAVHH02YABBY1DY","orval",null,"ComeOnOliver\u002Fskillshub","ComeOnOliver","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F43215937?v=4","01M6E5JNFECJAAVFE0W7SMWWD2","Haoran Shu","01M6E5JNNDQS7AJZDYFQ8TPZCK",67,"MIT","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fpproenca\u002Fdot-skills\u002Forval\u002FSKILL.md",[],[5],"2026-11-10 10:12:30",false,"# Orval OpenAPI Best Practices\n\nComprehensive guide for generating type-safe TypeScript clients from OpenAPI specifications using Orval. Contains 42 rules across 8 categories, prioritized by impact to guide automated configuration, client generation, and testing setup.\n\n## When to Apply\n\nReference these guidelines when:\n- Configuring Orval for a new project\n- Setting up OpenAPI-based TypeScript client generation\n- Integrating React Query, SWR, or Vue Query with generated hooks\n- Creating custom mutators for authentication and error handling\n- Generating MSW mocks for testing\n\n## Rule Categories by Priority\n\n| Priority | Category | Impact | Prefix |\n|----------|----------|--------|--------|\n| 1 | OpenAPI Specification Quality | CRITICAL | `spec-` |\n| 2 | Configuration Architecture | CRITICAL | `orvalcfg-` |\n| 3 | Output Structure & Organization | HIGH | `output-` |\n| 4 | Custom Client & Mutators | HIGH | `mutator-` |\n| 5 | Query Library Integration | MEDIUM-HIGH | `oquery-` |\n| 6 | Type Safety & Validation | MEDIUM | `types-` |\n| 7 | Mock Generation & Testing | MEDIUM | `mock-` |\n| 8 | Advanced Patterns | LOW | `adv-` |\n\n## Quick Reference\n\n### 1. OpenAPI Specification Quality (CRITICAL)\n\n- `spec-operationid-unique` - Use unique and descriptive operationIds\n- `spec-schemas-reusable` - Define reusable schemas in components\n- `spec-tags-organization` - Organize operations with tags\n- `spec-response-types` - Define all response types explicitly\n- `spec-required-fields` - Mark required fields explicitly\n\n### 2. Configuration Architecture (CRITICAL)\n\n- `orvalcfg-mode-selection` - Choose output mode based on API size\n- `orvalcfg-client-selection` - Select client based on framework requirements\n- `orvalcfg-separate-schemas` - Separate schemas into dedicated directory\n- `orvalcfg-input-validation` - Validate OpenAPI spec before generation\n- `orvalcfg-baseurl-setup` - Configure base URL properly\n- `orvalcfg-prettier-format` - Enable automatic code formatting\n\n### 3. Output Structure & Organization (HIGH)\n\n- `output-file-extension` - Use distinct file extensions for generated code\n- `output-index-files` - Generate index files for clean imports\n- `output-naming-convention` - Configure consistent naming conventions\n- `output-clean-target` - Enable clean mode for consistent regeneration\n- `output-headers-enabled` - Enable headers in generated functions\n\n### 4. Custom Client & Mutators (HIGH)\n\n- `mutator-custom-instance` - Use custom mutator for HTTP client configuration\n- `mutator-error-types` - Export custom error types from mutator\n- `mutator-body-wrapper` - Export body type wrapper for request transformation\n- `mutator-interceptors` - Use interceptors for cross-cutting concerns\n- `mutator-token-refresh` - Handle token refresh in mutator\n- `mutator-fetch-client` - Use fetch mutator for smaller bundle size\n\n### 5. Query Library Integration (MEDIUM-HIGH)\n\n- `oquery-hook-options` - Configure default query options globally\n- `oquery-key-export` - Export query keys for cache invalidation\n- `oquery-infinite-queries` - Enable infinite queries for paginated endpoints\n- `oquery-suspense-support` - Enable suspense mode for streaming UX\n- `oquery-signal-cancellation` - Pass AbortSignal for request cancellation\n- `oquery-mutation-callbacks` - Use generated mutation options types\n\n### 6. Type Safety & Validation (MEDIUM)\n\n- `types-zod-validation` - Generate Zod schemas for runtime validation\n- `types-zod-strict` - Enable Zod strict mode for safer validation\n- `types-zod-coerce` - Use Zod coercion for type transformations\n- `types-use-dates` - Enable useDates for Date type generation\n- `types-bigint-support` - Enable useBigInt for large integer support\n\n### 7. Mock Generation & Testing (MEDIUM)\n\n- `mock-msw-generation` - Generate MSW handlers for testing\n- `mock-use-examples` - Use OpenAPI examples for realistic mocks\n- `mock-delay-config` - Configure mock response delays\n- `mock-http-status` - Generate mocks for all HTTP status codes\n- `mock-index-files` - Generate mock index files for easy setup\n\n### 8. Advanced Patterns (LOW)\n\n- `adv-input-transformer` - Use input transformer for spec preprocessing\n- `adv-operation-override` - Override settings per operation\n- `adv-output-transformer` - Use output transformer for generated code modification\n- `adv-form-data-handling` - Configure form data serialization\n\n## How to Use\n\nRead individual reference files for detailed explanations and code examples:\n\n- [Section definitions](references\u002F_sections.md) - Category structure and impact levels\n- [Rule template](assets\u002Ftemplates\u002F_template.md) - Template for adding new rules\n- Example: [spec-operationid-unique](references\u002Fspec-operationid-unique.md)\n\n## Related Skills\n\n- For consuming generated hooks, see `tanstack-query` skill\n- For mocking generated API clients, see `test-msw` skill\n- For schema validation, see `zod` skill\n\n## Full Compiled Document\n\nFor the complete guide with all rules expanded: `AGENTS.md`\n",{},"main","def8531e65114c0fca8fb8551c1871ee0eed705c","skills\u002Fpproenca\u002Fdot-skills\u002Forval",24,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub","https:\u002F\u002Fskillshub.wtf","https:\u002F\u002Fgithub.com\u002FComeOnOliver","AI & Blockchain Engineer\r\n","2026-06-24 22:07:19",{"source":7,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add ComeOnOliver\u002Fskillshub --skill orval",{"tool":37,"command":38},"bunx","bunx skills add ComeOnOliver\u002Fskillshub --skill orval",{"tool":40,"command":41},"pnpm","pnpm dlx skills add ComeOnOliver\u002Fskillshub --skill orval","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fpproenca\u002Fdot-skills\u002Forval\u002FSKILL.md",true,[],[46,60,70,79,85,92],{"skillNo":47,"name":48,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":49,"categories":50,"keywords":56,"publishedAt":18},"01M6FKJN13GMG4KY57J3QD8GY5","model-hierarchy-skill","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzscole\u002Fmodel-hierarchy-skill\u002Fmodel-hierarchy-skill\u002FSKILL.md",[51],{"categoryNo":52,"categoryName":53,"taxonomyType":54,"taxonomyTypeDesc":55},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[57,58,59],"model","model hierarchy","model hierarchy skill",{"skillNo":61,"name":62,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":66,"publishedAt":18},"01M6FKJJJ6GCAMR4PPPRD12M5X","zoom-mcp","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-mcp\u002FSKILL.md",[65],{"categoryNo":52,"categoryName":53,"taxonomyType":54,"taxonomyTypeDesc":55},[67,68,69],"MCP","zoom","zoom mcp",{"skillNo":71,"name":72,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":18},"01M6FKJE3KYT3KPEZMEEHYKA6K","zoom-apps-sdk","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-apps-sdk\u002FSKILL.md",[],[76,77,78,68],"sdk","zoom apps sdk","apps",{"skillNo":80,"name":81,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":18},"01M6FKJ9EDH9Q5VWDF8HAJRSP0","windows","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwindows\u002FSKILL.md",[],[81],{"skillNo":86,"name":87,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":91,"publishedAt":18},"01M6FKJ666BEEFC3AE9GJ72Q93","whiteboard","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwhiteboard\u002FSKILL.md",[90],{"categoryNo":52,"categoryName":53,"taxonomyType":54,"taxonomyTypeDesc":55},[87],{"skillNo":93,"name":94,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":18},"01M6FKJ21WFCDGTJQ2Q91T9DVW","websockets","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwebsockets\u002FSKILL.md",[],[94]]