Developers / Skill file format

The skill file format

One file, one construct, plain Markdown. This page is the readable summary; the normative specification, a reference parser, a conformance corpus and worked examples live in the repository.

Read the full specification

Two conformance levels

A Core file just parses: frontmatter with a name and a description. It is usable as-is — an implementation can hand the body to a model verbatim. A Full file adds the body sections below, which is what lets a parser extract structure rather than prose. Real libraries contain both, so rejecting a definition-only file would be pedantry rather than validation.

Sections

Frontmattername, description: Must open the file at byte 0. `name` identifies the skill and `description` says what the construct is; both must be non-empty. Optional registered keys: `tag`, `include_context`, `version`, `evidence_mode`. A parser must ignore keys it does not recognise rather than reject the file — that is what lets the format grow.
# Definitionsrecommended: Criteria a careful reader who is not already an expert could apply. This is where a vague instrument becomes a decidable one.
# Examplesfor Full conformance: Positive and negative instances, marked `- TAG:` and `- NO-TAG:`, each with a one-line explanation opening “This is TAG because…”. The because clause matters: it is the shape the model imitates when justifying its own calls.
# Contrastive Learningfor Full conformance: Minimal pairs against confusable neighbours, with the discriminating feature named. Examples show a model the middle of a category; contrastive pairs show it the edge — which is where coders actually disagree.
# SCRATCHPADfor Full conformance: Questions to answer before deciding, numbered or bulleted. An exclusion checklist may follow, listing what rules the construct out and which neighbour to prefer instead.
# Severity Guideoptional: Ordinal anchors as `- N (Label): description`. Three usages are common: intensity (how severe), extent (how fully exhibited), and clarity (how plainly the item exemplifies its category) — the last for count-based instruments that have no intensity to rate. Omit for a purely categorical construct.
# Evaluation Process and Output Formatfor Full conformance: What the model must emit, including a fenced JSON example. Structured output is what makes results machine-scoreable rather than prose to be re-read.

A complete file

Deliberately not a clinical instrument: an unmarked change of subject is easy to state, has genuinely confusable neighbours, and belongs to nobody.

---
name: topic-shift-evaluation
description: Code speaker turns for an unmarked shift of conversational topic
tag: TSH
include_context: true
---

Classify each SUBJECT turn as TSH or NO-TSH. The preceding turn is needed to
decide, which is why include_context is set.

# Definitions

TSH (Topic Shift): the speaker moves to a subject unrelated to the immediately
preceding turn, without acknowledging the change.

# Examples

- TSH:
I: How has your sleep been this week?
S: My brother is selling his flat in Leeds.

This is TSH because the new subject cannot be derived from the question and no
marker signals the change.

- NO-TSH:
I: How has your sleep been this week?
S: Can I come back to that? I wanted to ask about the referral first.

This is NO-TSH because the change of subject is explicitly acknowledged.

# Contrastive Learning

- "My brother is selling his flat" after a sleep question (TSH: unrelated,
  unmarked) versus "Anyway - my brother is selling his flat" (NO-TSH: the marker
  acknowledges the move).

# SCRATCHPAD

- Is this the SUBJECT's turn?
- Could a listener derive this turn's subject from the previous one?
- Did the speaker mark the change in any way?

Exclusion checklist:
- Do not code TSH when a discourse marker acknowledges the shift.
- Do not code TSH for drift within a turn that began on topic.

# Severity Guide

- 1 (Marginal): a tenuous link to the previous subject may exist.
- 2 (Clear): a typical unmarked shift.
- 3 (Prototypical): wholly unrelated, with no marker of any kind.

# Evaluation Process and Output Format

Work through the scratchpad, then output JSON:

```json
{"label": "TSH", "severity": 2, "rationale": "..."}
```

Before you publish a skill file

The format is openly licensed. The instruments people encode with it often are not. Many rating scales are copyrighted, and some grant free use only for individual clinical or supervisory practice — an operationalised version is still a derivative work. Write your own operational wording rather than reproducing a manual, and record the instrument's terms in the file so whoever uses it next inherits the constraint instead of discovering it later.

Nothing in the specification grants rights over any instrument.