skills.rest
vstorm-co
vstorm-coOFFICIAL
Explore all skills by this author →
WebsiteGitHub

agent-spec

Guides backward-compatible changes to the Pydantic agent spec format and its migrations.

49|11|Updated Jul 31, 2026
Search Tags:#pydantic#validation#yaml#schema migration#data migration#backward compatibility#agent spec
One-click install
npx skills add https://github.com/vstorm-co/agenticos --skill agent-spec-vstorm-co
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agent-spec
Source: https://github.com/vstorm-co/agenticos/tree/main/.claude/skills/agent-spec
Command: npx skills add https://github.com/vstorm-co/agenticos --skill agent-spec-vstorm-co

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Changing the agent specification format risks breaking every published agent and every client git repository that stores a copy of it. This Skill encodes the rules for evolving app/agents/spec.py safely so old stored specs keep loading instead of failing with 500 errors. ## Core Features & Use Cases - Change Cost Table: Classifies each spec change (add, rename, remove, narrow a rule, move to a capability) by its migration cost and the required validator pattern. - Migration Invariants: Enforces idempotent mode="before" validators, publish-time refusal of invalid configurations, and data migrations shipped in the same change as narrowed rules. - YAML Round-Trip Contract: Preserves spec ordering and UUID string conversion so spec == AgentSpec.from_yaml(spec.to_yaml()) always holds. - Use Case: When adding a new field or tightening a validation pattern in the agent spec, follow this Skill to bump SPEC_VERSION, write the migration, and add a test loading a verbatim old document. ## Quick Start Use the agent-spec skill to add a new optional field to the agent spec in app/agents/spec.py with the correct default and migration test.

Frequently Asked Questions about agent-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new field to a Pydantic model without breaking stored data?▼

Add the field as optional with a default value so old stored documents take the default. If it must be required, supply the value through a mode="before" validator instead of making it mandatory.

How do I rename a field in a Pydantic model with existing data?▼

Use a mode="before" validator that moves the old key to the new name before validation runs. Keep the validator idempotent so re-reading an already-migrated document changes nothing.

Why does narrowing a Pydantic validation rule break existing rows?▼

A narrower pattern or shorter max length makes previously stored values fail validation, and one failing field can take down an entire listing endpoint with a 500. Find every stored value and ship a data migration in the same change.

When should validation happen at publish time versus run time?▼

Refuse invalid configurations like unknown capability ids, ungranted scopes, or wrong secret references at publish time while a user is viewing a form. Validation added only to the runner produces broken agents in production.

How do I test a spec migration correctly?▼

Write a test that loads a verbatim old document rather than one built from the current model, which cannot fail. Also test the YAML round-trip and each publish-time refusal case.

Related Skills

Explore More Software Engineering Skills→
SeaCloudAISeaCloudAI
1

viduq2_pro_start_end2video

Translate the live Vidu Q2 Pro JSON model spec into a seacloud run command.

Official
Advanced
ohmyhotelcoohmyhotelco
1

fm-parity

Runs visual, API contract, WebView bridge, and telemetry parity gates on migrated pages before route flip.

Official
Advanced
marvelousempiremarvelousempire

migration-shipping

Validate migration files and smoke test affected endpoints before deployment.

Community
Advanced
soham2008xyzsoham2008xyz

refactor

Restructure existing code without changing observable behavior.

Community
Intermediate