Summary
A skill is a procedure written in plain language that the assistant reads and applies: a statistics reference, the right way to query an OMOP warehouse, your unit’s conventions. The format is an open standard, read by many assistants. Linkr already ships a concept-mapping skill, to import into LibreChat; managing skills inside Linkr, at workspace level, is planned.
The problem: explaining it again every time
A language model has general knowledge, but approximate where it needs to be exact. It will confuse two statistical tests with neighbouring assumptions. It will write a plausible but wrong OMOP query, because it does not know a concept must be looked up in both _concept_id and _source_concept_id. And it certainly does not know your unit’s practices.
You can correct it in every conversation. Or write it down once.
That is exactly what a skill is: a reference procedure, written to be read by an assistant rather than filed in a drawer.
Three families emerge quickly in practice.
A methodological reference
Statistics, for instance: which test for which question, under which assumptions, how to report the result. The assistant helping you write code then works from sourced knowledge rather than approximate recollection.
How to query your warehouse
The usual queries against the OMOP model — or whichever format you use — with their traps. An assistant that has read this skill writes SQL that is correct on your model, instead of plausible generalities.
Your unit’s practices
What no model can guess: your usual inclusion criteria, your naming conventions, the exclusions you apply as a matter of course.
What it looks like
A skill is a folder holding a SKILL.md file, and optionally supporting files: examples, a document template, a script.
The SKILL.md header
namethe skill's identifierdescriptionwhen to use it: the assistant decides on thislicensethe terms for reusing itmetadata.versionthe version to cite in a publicationThe file opens with a header — a name, a description — and the body is free text.
---
name: omop-queries
description: >-
How to query an OMOP-format warehouse: usual queries, joins on
concepts, traps to avoid.
---
# Querying an OMOP warehouse
## Always look a concept up on both columns
An event carries a `_concept_id` (the standard concept) and a
`_source_concept_id` (the original code). Searching only one of them
misses records: always query both. …
## Count patients, not rows
The same measurement can appear several times for one patient. Unless
asked otherwise, count distinct `person_id`. …Nothing more. No programming language, no build step: text you read and correct like any other procedure note. That is what lets a clinician write one without an intermediary.
The description matters more than you would think
The description is what the assistant uses to decide whether to read a skill at all. A vague one will make it miss the skill; one that states precisely when to reach for it makes the skill useful at the right moment.
The concept-mapping skill
Linkr ships one skill today, concept-mapping, to map a hospital’s local codes to standard OMOP concepts. An agent following it works directly in a mapping project, through the MCP server:
- it goes through a category’s source concepts and reads their metadata — units, value distribution, wards where the code is used — to decide between close targets;
- it searches for candidates in the project’s OMOP vocabulary, or first in a data dictionary — the workspace’s concept sets — when you ask it to;
- it leaves its proposals as AI suggestions, each with its equivalence and a comment justifying the choice. You review them in the Suggestions tab;
- it creates mappings only for the choices you confirmed, and always with the “unchecked” status.
SKILL.md
The method: read the metadata, justify, validate nothing alone.
Follows the method
Looks for candidates through the MCP server's tools.
AI suggestions
You review them in the Suggestions tab.
Metadata goes to the model
The source concepts’ metadata — ward names, value distributions — is sent to the model. With a remote model, keep this skill for open data, or for data you are allowed to send to that provider. See The question of the model.
Installing it
- In LibreChat — the administrator builds the skill archive from Linkr’s repository (
npm run skill:packinpackages/linkr-mcp, which createsdist/concept-mapping.zip), then imports it in LibreChat’s Skills area. Then enable the skill and the Linkr MCP server’s tools for your agent, and ask for instance: “Map the unmapped concepts of the Blood Gas category in the MIMIC-IV Demo project.” - In OpenCode, or any client that reads the Agent Skills format — load the repository’s
packages/linkr-mcp/skills/concept-mappingfolder.
The skill carries a version number and a changelog, so the exact version used can be cited in a publication. After an update, re-import it into LibreChat.
Managing skills in Linkr — planned
Planned feature
This feature is not available yet. Here is what is planned, so you can tell whether it will cover your need — and tell us if it will not.
Status — design settled
Planned availability — server mode only
Written once, picked per project
Skills belong to the workspace — the right level, since a unit convention applies to every project that depends on it.
Each project then picks the ones it uses. An analysis project will enable the statistics reference; a project working against the warehouse will enable the OMOP query one. There is no point drowning the assistant in procedures that have nothing to do with the work at hand.
One important point: an exported project carries a reference to the skills it uses, not a copy. Otherwise every project would end up with its own drifting version of the same procedure — precisely what writing it once is meant to prevent. If a referenced skill is missing on import, Linkr says so and offers to install it.
An open standard, not a Linkr format
This is where skills outlast Linkr: the format is an open standard, already read by many assistants on the market.
It is already what lets the concept-mapping skill work in LibreChat as well as in OpenCode. Likewise, a skill written for Linkr — “how to query our OMOP warehouse” — stays readable by the assistant in your code editor, on your machine, outside any Linkr instance. It is not an investment in a tool, but in a procedure reusable elsewhere.
It is also what makes skills shareable: published to the catalog, a skill benefits other institutions, who can adapt it to their own practices.
A typical use
A centre writes a statistics skill: which test for which question, the assumptions, how to report the result, all of it referenced. The assistant helping write an analysis leans on it instead of reconstructing from memory. Published, that skill serves other centres — and the methodological review benefits everyone.
What is not settled yet
- Sharing files between skills. The standard pushes towards self-contained skills, so each one carries what it needs; whether that is enough in practice remains to be seen.
- How much checking to do at writing time: a malformed skill is silently ignored by assistants, which is painful to diagnose — what Linkr flags, and when, is still to be decided.
Going further
- Agents — the assistant that reads these skills and applies them.
- MCP server — connecting LibreChat or OpenCode to Linkr.
- Publishing content — sharing a skill with other institutions.