API DESIGN / JetBrains
Error Model Validation Architect
Turns ad-hoc exception handling into a deliberate public error contract: an explicit taxonomy across eight failure categories, status-code mapping rules, machine-readable codes separated from human messages, framework exception coverage, and a logging rule that keeps internal detail out of client payloads.
“Design and implement consistent API validation and error-handling behavior for Kotlin plus Spring services. Use when defining error payloads, mapping framework and domain exceptions, standardizing HTTP status codes, adding `@ControllerAdvice`, preventing internal-detail leakage, or ensuring clients can rely on stable machine-readable error semantics across endpoints.”
01 / THE REASONING
Why this made the selection.
- Forces an explicit error taxonomy before any code — at minimum eight categories from malformed request to downstream dependency failure — and forbids collapsing every non-success outcome into one generic envelope.
- Pins specific status-code decisions: 409 for idempotency-key and uniqueness races, 422 for structurally valid but business-invalid payloads, and downstream 500s that must not blindly become your own 500.
- Separates the two audiences of an error — the client who needs to recover and the operator who needs to diagnose — and makes leaking stack traces, SQL fragments, class names or tokens a named guardrail.
02 / THE REVIEW RECORD
What we actually inspected.
Source review has boundaries.
A clear record is more useful than a “safe” badge.
Material inspected
- error-model-validation-architect/SKILL.md (JetBrains mirror)
- error-model-validation-architect/agents directory listing
- upstream yalishevant/kotlin-backend-agent-skills .agents/skills/error-model-validation-architect/SKILL.md
- upstream LICENSE
- JetBrains/skills README mirror policy
- https://github.com/Kotlin/kotlin-backend-agent-skills (answers HTTP 301 to yalishevant/kotlin-backend-agent-skills)
- mirror SKILL.md diffed against the upstream SKILL.md at fd0ed521d22efd28221d532c9abab97af0b9bf0e
Our findings
- The output contract demands six named sections (taxonomy, status mapping, payload shape, framework coverage, implementation plan, logging rule), which makes a run reviewable against its own claims.
- Names the exact framework exceptions a stable contract must handle explicitly — MethodArgumentNotValidException, HttpMessageNotReadableException, type-mismatch, missing-parameter, and the security entry points — rather than trusting defaults.
- A diff against the upstream SKILL.md at fd0ed521d22efd28221d532c9abab97af0b9bf0e shows the mirror adds four frontmatter lines (metadata, short-description, author: Kotlin, source) and nothing else; the upstream file has no author field. agents/openai.yaml is identical in both.
- Upstream health: https://github.com/Kotlin/kotlin-backend-agent-skills, which the mirror’s metadata.source and README name, now answers HTTP 301 to yalishevant/kotlin-backend-agent-skills, a personal account (https://api.github.com/repos/Kotlin/kotlin-backend-agent-skills returns full_name yalishevant/kotlin-backend-agent-skills, owner type User). fd0ed521d22efd28221d532c9abab97af0b9bf0e is still that repository’s head, and its LICENSE (MIT, copyright 2026 Anton Yalyshev) is unchanged (checked 2026-10-13).
Not established by this review
- No error model was implemented or served; the design rules were read, not executed.
- The agents/openai.yaml companion file was noted but not exercised.
The review applies to the material and revision named here. A newer upstream release can change its behavior.
03 / PUT IT TO WORK
Add a skill to your workflow.
DOCUMENTED COMMAND
npx skills add JetBrains/skills/error-model-validation-architect --skill error-model-validation-architectRun in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.
Optional: install the reviewed revision
Keeps the original source and installer version where recorded, while leaving your AI tools and installation scope for you to choose.
npx skills add https://github.com/JetBrains/skills/tree/e0f258b5cfed145015cb3e48da9a97947f7c4ed7/error-model-validation-architect --skill error-model-validation-architect- Install the skill from the JetBrains mirror, or from the upstream Kotlin backend agent skills repository if you prefer the origin.
- Bring the endpoint contracts, current exception classes and any existing error payloads; the output contract expects them as inputs.
Before you start
- Node.js/npm for the installer
- An agent that supports the Agent Skills format
- The API whose error contract is being designed or audited
04 / FOLLOW THE EVIDENCE
The source trail.
Our notes are separate from the original resource.
Check upstream before adopting a new version.
https://github.com/JetBrains/skills/blob/e0f258b5cfed145015cb3e48da9a97947f7c4ed7/error-model-validation-architect/SKILL.md
Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, access
https://github.com/yalishevant/kotlin-backend-agent-skills/blob/fd0ed521d22efd28221d532c9abab97af0b9bf0e/.agents/skills/error-model-validation-architect/SKILL.md
Supports: review, whySelected, limitations
- Upstream license (MIT) ↗Checked
https://github.com/yalishevant/kotlin-backend-agent-skills/blob/fd0ed521d22efd28221d532c9abab97af0b9bf0e/LICENSE
Supports: license
https://github.com/Kotlin/kotlin-backend-agent-skills
Supports: review, limitations
https://github.com/JetBrains/skills/blob/e0f258b5cfed145015cb3e48da9a97947f7c4ed7/README.md
Supports: review, install, limitations
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md
Supports: install