CD openapi
Vovk.ts OpenAPI generation — how the OpenAPI 3.x spec is derived from procedures + validation schemas, the `@operation` decorator family (`@operation({...})` for summary/description/tags/security/deprecated, `@operation.error(status, message)` for error responses, `@operation.tool({...})` for AI tool metadata), top-level `outputConfig.openAPIObject` configuration (info, servers, license, tags, security, components), per-segment overrides, accessing the spec from code (`@/client/openapi`), serving the spec JSON from a controller, and rendering it with **Scalar** (the primary / recommended docs UI — picks up the TypeScript / Python / Rust code samples that Vovk generates via `x-codeSamples`) or alternatives like Redoc / Swagger UI. Use whenever the user asks for "API docs", "Scalar docs", "Swagger", "OpenAPI spec", "document my API", "generate OpenAPI from my controllers", "add an info/title/servers block", "segment-specific docs", "expose OpenAPI at /api/docs", "bearer auth in the spec", "document possible errors", "deprecate an endpoint". Does NOT cover procedure authoring → hand off to `procedure` skill. Does NOT cover AI tool derivation via `deriveTools` → hand off to `tools` skill (though `@operation.tool` is mentioned here since it's part of the decorator family). Does NOT cover third-party OpenAPI imports → hand off to `mixins` skill.
This skill teaches an AI to generate OpenAPI 3.x from Vovk.ts procedures and validation schemas. Promises: `@operation` decorators for metadata (summary, tags, security), `@operation.error()` for error responses, `@operation.tool()` for AI metadata, top-level `outputConfig.openAPIObject` config, spec access via `@/client/openapi`, and Scalar rendering with auto-generated code samples.
The file contains one instruction (3240 tokens) with no examples or test runs. Grade C (quality 59%, process 47%) signals incompleteness: the description is dense with details but shows no working examples. Linter complains about length. No critical errors, but no sandbox either to verify the decorators produce valid OpenAPI or that Scalar picks up the samples.
Install if you're already using Vovk.ts and need decorator syntax reference. If the AI must write `@operation` with correct parameters independently, add real controller examples first.
Vovk.ts OpenAPI generation — how the OpenAPI 3.x spec is derived from procedures + validation schemas, the @operation decorator family (@operation({...}) for…
As a process D 47/100 · Unfinished process — weak spots: result and completion, inputs and preconditions, failures and branches
How to improve
- Shorten the description to 1024 characters.
- Your own cases (evals/evals.json, 4–6 real requests with expected answers): the full check would then run those instead of a model-drafted suite.
- A spec.yaml with trigger phrases and assertions — a behaviour contract for CI; `skilltest init` writes a template.
Guard findings · 0
✓ No critical or high findings
Files scanned: 1. Evidence is masked. Grey chips explain why severity was lowered.
Against the Agent Skills spec
- error
description-longdescription is 1361 chars, limit 1024 - note
edit-residuethe text marks something as outdated (lines 25, 40, 283): check that old rules are not kept next to new ones — the full check reads the text for contradictions
Process rating: all ten parameters 47/100
- 0Result and completion. Does not say what the result is
- 0Inputs and preconditions. Does not say what the process needs to start
- 0Failures and branches. Linear process with no failure handling
- 0Progress reporting. Says nothing while it works
- 30Running it twice. 4 mutating operations with no state check
- 60Tools and files. Uses tools (bash, web, python) that frontmatter does not declare
- 70When it triggers. States when to use, but not when not to
- 85Steps. 9 steps, 2 vague phrases
- 100Consistency. Name and required fields are in place
- 100Execution cost. Instruction body is 3240 tokens
Everything here is measured from the skill text rather than judged by a model, so the numbers are checkable. A parameter weighs more when it is a more common reason for the process to stall.
Quality signals
- +4Description does not say when NOT to use the skill (false activations)
- +3Description length 1361: 120–800 characters recommended
- +3Output format is not stated: the model decides each time
- -2localhost URLs: will not work for another user
- +1No license
- +2Single-language instructions
- +5Description quotes 12 example trigger phrases
- +4Structure: 23 headings
- +3Step-by-step instructions: 9 items
- +4Has examples (14 code blocks)
Quality base 70; lint remarks subtract, signals add up to 100. Result: 59.