# Fix Validation Errors With Overlays

> Use when you have lint errors but can't modify the source spec, or need to add missing descriptions/tags via overlay

- Skill: `diegosouzapw/fix-validation-errors-with-overlays` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/fix-validation-errors-with-overlays`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/fix-validation-errors-with-overlays/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/fix-validation-errors-with-overlays

---


# fix-validation-errors-with-overlays

## Overlay-Appropriate Fixes

| Issue | Overlay Solution |
|-------|------------------|
| Poor operation names | `x-speakeasy-name-override` |
| Missing descriptions | Add `summary` or `description` |
| Missing tags | Add `tags` array |
| Need operation grouping | `x-speakeasy-group` |
| Need retry config | `x-speakeasy-retries` |

## NOT Overlay-Appropriate

| Issue | Why |
|-------|-----|
| Invalid JSON/YAML | Syntax error in source |
| Missing required fields | Schema incomplete |
| Broken $ref | Source needs fixing |
| Wrong data types | API design issue |

## Quick Fix Workflow

```bash
# 1. Generate suggestions
speakeasy suggest operation-ids -s openapi.yaml -o fixes.yaml

# 2. Add to workflow
# Edit .speakeasy/workflow.yaml to include overlay

# 3. Regenerate
speakeasy run
```