DBTable Skills

Structured Data Workflows

Structured table skills are necessary whenever the operational domain contains records, fields, identifiers, relations, and constraints that must remain stable across repeated interactions. An inventory system, for example, may include stock-keeping unit (SKU) codes, prices, stock levels, and supplier references. In such a setting, an unconstrained model may produce values in the wrong format, omit required fields, or ignore relations that are necessary for downstream consistency. These failures are not merely stylistic. They propagate into storage, reporting, and later processing stages.

Whenever user input can alter persistent state, the cost of ambiguity becomes cumulative. A missing identifier, an invalid format, a silently ignored relationship, or an inconsistent field interpretation may affect not only one response but every later operation that depends on the stored record. For this reason, table-oriented workflows cannot rely only on conversational plausibility. They require a more explicit and more stable contract.

DBTable Skills emerged from this kind of operational pressure. The underlying problem was not that language models were useless in data workflows, but that flexibility alone was insufficient wherever correctness had to persist across repeated interactions. A useful system had to understand not only what operation a user was requesting, but also how that operation had to be carried out under established field semantics, validation rules, and business constraints.

The resulting solution was not to remove intelligence from the interaction, but to place it inside an explicit structural framework. The language model remains responsible for interpretation, guidance, and interaction management, while the skill definition supplies the commitments that cannot be left to improvisation. In this way, the subsystem remains helpful to the user while also remaining disciplined with respect to the data model.

DBTable Skills therefore provide a common structure for create, read, update, and delete operations, so that repeated interactions are evaluated against the same validation logic and field semantics. They centralize business rules in the skill definition itself, reduce the risk that ad hoc prompts or local patches bypass the intended data contract, and support guided correction flows and confirmation stages when the interaction requires several steps. From a maintenance perspective, the same source specification can be read by a human, transformed by the generation pipeline, and later verified through explicit tests.

How the Subsystem Works in Practice

The workflow begins with a tskill.md document that describes the table purpose, the available fields, and the optional behavioral constraints associated with those fields. This specification is parsed into a structured representation that the subsystem can validate and transform. From that point onward, the skill ceases to be mere documentation and becomes an executable contract for downstream code generation and runtime behavior. The practical rules for writing that source file, together with minimal and extended examples, are described in Authoring.

When the skill is prepared, the subsystem parses the specification, validates the resulting structure, generates a spec file for the code-generation stage, and loads the generated runtime module. During execution, the conversational controller interprets the incoming request, decides which table operation is being attempted, applies the relevant preparation and validation functions, and maintains pending confirmation or correction state when the interaction requires multiple steps. The result is a controlled path from user request to record-level operation rather than an unrestricted conversational guess.

The central technical distinction is therefore the distinction between source specification and executable artifact. A human maintainer edits tskill.md. The subsystem derives specs/tskill.generated.mjs.md from that source and then produces src/tskill.generated.mjs through code generation. At runtime, the subsystem imports and calls the generated module under src/. The markdown file remains authoritative, but it is not the file that is executed when a record operation takes place. The transformation path and runtime role of the generated module are examined in greater detail in Runtime.

The maintainability of the subsystem depends on keeping three activities distinct. The specification should be revised in tskill.md, the executable logic should be regenerated rather than edited manually, and the resulting behavior should be verified through explicit tests. This separation preserves traceability between intention, generated logic, and observed runtime behavior. For this reason, test files are treated as human-maintained artifacts rather than generator output. The corresponding testing model, together with validator examples and repository commands, is discussed in Testing.