| name | schema-updater |
| description | Research-backed JSON Schema refresh workflow for updating existing schemas with validation checkpoints and cross-reference verification. |
| version | 1.0.0 |
| model | sonnet |
| invoked_by | both |
| user_invocable | true |
| tools | ["Read","Write","Edit","Glob","Grep","Bash","Skill","MemoryRecord"] |
| args | --schema <name-or-path> [--trigger reflection|evolve|manual|stale] [--mode plan|execute] |
| error_handling | graceful |
| streaming | supported |
| verified | true |
| lastVerifiedAt | 2026-04-07 |
| dependencies | ["research-synthesis"] |
| category | framework-management |
| tags | ["schemas","updater","maintenance","framework","json-schema"] |
| aliases | ["update-schema","refresh-schema"] |
| source | builtin |
| trust_score | 100 |
| provenance_sha | 4865f95be2ca25db |
Schema Updater
Overview
Use this skill to refresh an existing JSON Schema safely: research current best practices, compare against the artifact it validates, generate a TDD patch backlog, apply updates, and verify ecosystem integration.
When to Use
- Schema no longer matches the artifact structure it validates
- New fields added to skills/agents/hooks/workflows but schema not updated
- Reflection flags schema validation failures
- User asks to audit/refresh an existing schema
The Iron Law
Never update a schema blindly. Every refresh must be evidence-backed, TDD-gated, and integration-validated.
Workflow
Step 0: Evaluate Current State
- Read the schema file and understand what it validates
- Find the artifacts it validates (skills, agents, hooks, workflows)
- Compare schema required fields against actual artifact structure
- Identify gaps: missing fields, wrong types, stale descriptions
Step 1: Research Best Practices
- Read
.claude/schemas/CLAUDE.md for schema conventions
- Review similar schemas for patterns
- Check JSON Schema Draft-07 specification compliance
- Use
Skill({ skill: 'research-synthesis' }) if external research needed
Step 2: Generate Patch Backlog
- List specific changes needed
- Prioritize: required field additions > type corrections > description updates
- Ensure backward compatibility where possible
Step 3: Apply Updates
- Write or update validation tests first (RED phase)
- Apply schema changes (GREEN phase)
- Refactor for clarity (REFACTOR phase)
- Use
Edit tool — never rewrite the entire file
Step 4: Verify Integration
- Verify schema is valid JSON Schema Draft-07
- Verify
$id and $schema fields are present and correct
- Validate at least 3 existing artifacts against the updated schema
- Run
pnpm lint:fix && pnpm format
- Run schema validation tests
Step 5: Record
- Log changes via
MemoryRecord if significant
- Update CHANGELOG.md entry
Domain-Specific Validation
- Schema MUST be valid JSON Schema Draft-07 (
$schema: "http://json-schema.org/draft-07/schema#")
