metaobjects-authoring

Author MetaObjects metadata entities, fields, and relationships in YAML or canonical JSON.

1|Updated May 14, 2026
One-click install
npx skills add https://github.com/metaobjectsdev/metaobjects --skill metaobjects-authoring-metaobjectsdev
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: metaobjects-authoring
Source: https://github.com/metaobjectsdev/metaobjects/tree/main/agent-context/skills/metaobjects-authoring
Command: npx skills add https://github.com/metaobjectsdev/metaobjects --skill metaobjects-authoring-metaobjectsdev

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Writing MetaObjects metadata by hand is error-prone: the fused-key encoding, reserved structural keys, closed field subtype vocabulary, and attribute placement rules are easy to get wrong, and mistakes surface as load failures or drift between the model and generated code. This Skill provides the authoritative procedure for declaring entities, fields, relationships, sources, enums, and requirements correctly the first time. ## Core Features & Use Cases - Model-first authoring guidance: Enforces the declare-then-generate workflow so persistence, validation, APIs, and UI scaffolding are derived from metadata rather than hand-written. - Vocabulary decision procedure: Applies the ADR-0037 ordered tests (derive, dbColumnType, subtype, @kind, attribute) to choose the correct shape for any concept, including custom provider registration. - Adoption mode for existing codebases: Reverses direction when working code or a live schema exists, modeling metadata to reproduce native types, column names, and nullability already in use. - Use Case: When adding a User entity with a UUID primary key, an email field, and audit timestamps, the Skill directs you to field.uuid, field.string with @stringFormat: email, and field.timestamp with @autoSet, avoiding the field.string + @dbColumnType: uuid anti-pattern. ## Quick Start Ask the agent to declare a new MetaObjects entity with its fields and identity in a metaobjects/ metadata file, following the fused-key encoding and vocabulary rules.

Frequently Asked Questions about metaobjects-authoring

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

FAQPage Schema
How do I declare an entity in MetaObjects metadata?

Declare an entity with the fused-key form object.entity containing a name and children for fields, a source.rdb node for the table, and an identity.primary node for the key. Files live under metaobjects/ and declare a package on the root node.

How do I model a UUID column in MetaObjects?

Use the field.uuid subtype, which generates a native UUID type in every target language. Never use field.string with @dbColumnType: uuid, because that generates a String property over a uuid column and forces coercions at every boundary.

What is the difference between YAML and canonical JSON metadata?

Both express the same fused-key encoding, but canonical JSON prefixes attributes with @ while YAML leaves attributes bare and the desugar re-adds the prefix. Reserved structural keys like name, extends, isArray, and children are bare in both formats.

When should I create a custom subtype versus an attribute?

Follow the ADR-0037 ordered tests: derive from existing constructs first, then a subtype only when the concept has its own native type or behavior, @kind for structural variants within a subtype, and an attribute for validation or configuration of an existing type.

Can I adopt MetaObjects onto an existing database schema?

Yes, adoption reverses the direction: read the existing code and schema first, then author metadata to reproduce native types, column names, nullability, and table names so verify --db passes. Customize the generator or template rather than reshaping working code.

Why does my metadata fail to load with ERR_RESERVED_ATTR?

The error occurs when a reserved structural key such as isArray is @-prefixed, since reserved keys must stay bare. Use isArray: true in YAML or the [] key-suffix sugar like field.long[] instead.