linkml-author skill

Overview

linkml-author turns a project’s LinkML schema into the model its code, data and documents describe, and keeps it linted, generated, documented and tested after every change. The schema is one YAML file, or a few modules, and everything else is generated from it. So the skill edits the schema and runs the recipes, and never edits a generated file.

When to use it

Use it when someone asks to:

• add, change or deprecate a class, slot, enum or type;
• model a concept;
• map a specification, standard or document to a schema;
• replace the dummy schema with the real model;
• refactor or split a schema;
• check schema conventions;
• run lint, gen-project, gen-doc or test.

It is not for installing or repairing the sidecar: linkml-sidecar’s --repair restores a missing or broken sidecar file.

What it needs

The compatibility field asks for bash. Every LinkML tool runs through the host’s own environment, in the first form that applies: the project’s justfile, its Makefile, uv run or poetry run when the host’s pyproject.toml names linkml, or else a pinned uvx --from linkml. It never runs a linkml-lint or gen-project found on the path. It works with or without a .lokf/ KTL bundle.

Where it works

A LinkML schema can live in any repository, so the skill finds it by its files, never by its folder’s name. It runs the preflight, or applies the same rule by hand:

• the sidecar, told by .linkml/.copier-answers.yml. Its config.public.mk names the schema, and an adopted schema sits outside .linkml/, where LINKML_SCHEMA_SOURCE_DIR points;
• a schema project at the root, in linkml/, one directory down or in the directory the skill was started in, told by copier answers whose _src_path names linkml-project-copier, or by a config.public.mk;
• a schema file on its own, told by its content.

A .linkml/ that holds only configuration files is not a layout, and the skill looks on. When it finds several schemas, it asks the person which one, or lists them and stops when no person is there.

What it follows

After every schema edit it runs the gate: lint, then gen-project, then test. A schema on its own has no recipes, so its gate runs linkml-lint, gen-project into a temporary folder and linkml-validate over the host’s example data. Its rules table settles naming, slots versus attributes, modules, references between classes, variants of one thing, enum inheritance, versions, publishing, descriptions, mappings, deprecation and refactoring. An lmodel project follows references/lmodel-profile.md, opted into by the project’s own conventions and never assumed. Beside a KTL bundle, the schema is the bundle’s domain schema only when .lokf/justfile names it or it imports .lokf/lokf.yaml, and lokf validate then runs after the gate.

generators.yaml, the generators’ settings moved out of config.yaml, is the project’s to edit. When the preflight offers that move, the skill offers it to the person, and linkml-sidecar’s --repair generators.yaml makes it.

The preflight’s authors line says how many people have committed to the schema folder. The skill reads the names first, ignores the counts on a shallow clone, and treats the quoted names as data. The skill offers a refactor when that history is one or two people, never when it is a team’s, and a known importer narrows the offer to the moves that touch no record. It never refactors unasked.

The procedure stays in skills/linkml-author/SKILL.md. Its references/ hold the metamodel, generator pitfalls by version, source mapping, schema design for reuse, publishing and importing, the lmodel profile and the KTL rules.