DBTable Skills

Skill Layout

Each DBTable skill lives under .AchillesSkills/<domain>/<table>/ with two important files:

• tskill.md – the Markdown descriptor that defines the table, field metadata, and behavioural hints.
• tskill.generated.mjs – generated by DBTableSkillsSubsystem and rebuilt whenever tskill.md changes; exports helpers such as prepareRecord and presentRecord.

RecursiveSkilledAgent discovers directories that contain tskill.md, assigns them canonical names like projects-dbtable, and delegates preparation and execution to DBTableSkillsSubsystem. When callers omit args, the subsystem injects the task description into the default argument prompt before execution.

Descriptor Anatomy

A descriptor uses headings to describe both the table overview and each field. Sub-chapters such as Description, Field Name Presenter, Enumerator, Resolver, Validator, Derivator, and PrimaryKey are parsed into the blueprint:

# Projects
Track internal initiatives and their lifecycle status.

## Table Purpose
Provide lifecycle visibility by listing, creating, or updating projects.

## Field: project_id
### Description
Unique identifier users refer to in chat.
### Field Name Presenter
Project ID
### Resolver
Normalise inputs like `PRJ1` or `Project 1` into the canonical `PRJ-001`.
### PrimaryKey
If empty, generate a PRJ- prefixed identifier with padded counters.

## Field: status
### Required
Status is mandatory when creating or updating records.
### Enumerator
- planned: scheduled but not started
- active: currently in delivery
- complete: fully delivered
### Validator
Reject anything that is not one of planned/active/complete.

Authoring guidelines:

• Use one ## Field: name section per column. Headings must be unique.
• Bulleted lists under Aliases or Enumerator are parsed automatically; free-form text also works.
• Derivator sections describe read-only fields computed via LLM prompts. They are excluded from persistence.
• Grouping declares cross-table helpers (buildGroupingAccessor) when Persisto exposes richer relations.

Compilation Pipeline

When a descriptor changes, DBTableSkillsSubsystem parses it into a blueprint and rewrites tskill.generated.mjs. The generated module exports:

• functions – a bundle containing prepareRecord, validateRecord, presentRecord, enumerators, resolvers, and derivators.
• blueprint – normalised table metadata, field ordering, and descriptor hash.

These helpers feed directly into the subsystem executor so the Markdown stays the single source of truth.

Supported Operations

The runtime uses LLMAgent to classify the user prompt into CREATE, UPDATE, SELECT, or DELETE, passing descriptor instructions and a field list into that classification prompt. It then runs the generated helpers and uses the configured dbAdapter to apply the change:

• CREATE: Resolve and validate incoming fields, derive defaults, and insert via dbAdapter.insert.
• UPDATE: Merge provided fields, validate, and persist with dbAdapter.update.
• SELECT: Query via dbAdapter.query and present rows with generated presenters.
• DELETE: Remove records using dbAdapter.delete after confirmation of filter/keys.

Argument collection is handled inside the generated functions (resolvers, derivators, validators); there is no interactive-forms layer in this subsystem.

DB Adapter Contract

DBTable skills delegate persistence to a dbAdapter supplied when constructing DBTableSkillsSubsystem. Implement at least query(tableName, filter), insert(tableName, record), update(tableName, id, data), and delete(tableName, filter) to mirror the operations above. The subsystem will register table metadata if the adapter exposes addType or addModel.

Testing

Run the integration suite with node --test tests/dbTableSkills/dbTableSkills.test.mjs to validate parsing, generation, and CRUD flows against a mock adapter. The tests ship with sample skills under tests/dbTableSkills/.AchillesSkills/ that you can use as references when authoring your own tskill.md files.