Writing a SKILL.mtx

A SKILL.mtx defines how the MCL compiler handles a specific verb or intent type. It declares the skill's metadata, input/output slots, procedure (decision tree), tools, sub-skills, and failure modes. The compiler runtime (mclc) interprets the file; the Go code contains no compile logic.

Source files: mtx/spec.md, mtx/validator/, core/ (framework modules).

File location

Skill files live at skills/<slug>/SKILL.mtx and must contain a SKILL section. The id field must match the directory name.

Required sections

A valid SKILL.mtx must contain:

Section	Required	Purpose
`SKILL`	Yes	Metadata: id, version, display, author, description, verbs
`INPUTS`	Yes	Slot declarations for the skill's inputs
`PROCEDURE`	Yes	Decision tree: `on`-blocks with prompts, resolves, unknowns, clarifies
`OUTPUTS`	Yes	Produced slot declarations
`TOOLS`	Yes	`none` or list of `matrix://tool/...` URIs
`SUB_SKILLS`	Yes	`none` or list of `matrix://skill/...` URIs
`FAILURE_MODES`	Yes	Named failure modes with actions
`CORTEX`	No	Memory access declaration (reads, tags)

Minimal example

SKILL
id=writing-plans
version=1.0.0
display=Writing Plans
author=did:pax:dev:a]b2c3d4e5f6a7b8
description=Converts a build/modify intent draft into a structured plan
mcl.verbs=build modify
determinism=seedable

INPUTS
slot target: ArtifactRef
  required
  hint="The artifact to build or modify"

slot style: enum<formal|casual|technical>
  optional
  default=formal

CORTEX
reads=Preference Goal Constraint Event Fact Pattern
tags=writing planning

TOOLS
none

SUB_SKILLS
none

PROCEDURE
on verb=build
  prompt
    system="You are the Matrix plan compiler. Fill the Frame for a 'build' intent."
    user="User goal: {prose}. Context: {cortex.bundle}. Known slots: {slots}. Fill the Frame JSON."
  end
  resolve slot.target <- cortex.find(type=Fact, near=slot.target.prose, limit=5)
  unknown slot.target
    severity=blocking
    reason="Cannot identify the target artifact from the user's phrasing"
  end
end

on verb=modify
  prompt
    system="You are the Matrix plan compiler. Fill the Frame for a 'modify' intent."
    user="User wants to modify: {prose}. Current state: {slot.target}. Fill the Frame JSON."
  end
  resolve slot.target <- cortex.resolve(slot.target.prose)
  unknown slot.target
    severity=blocking
    reason="Need to identify what is being modified"
  end
end

on confidence<0.75
  clarify slot.target
    prompt="Which artifact are you referring to?"
    type=ArtifactRef
    required=true
  end
end

OUTPUTS
slot plan_draft: PlanDraft
  required

FAILURE_MODES
budget_exceeded
  suggest=raise_budget
tool_missing
  action=fail
  reason=tool_failure

SKILL section fields

Field	Type	Required	Notes
`id`	string	Yes	Slug, matches directory name
`version`	string	Yes	Semver
`display`	string	Yes	Human label
`author`	did	Yes	Signing key
`description`	string	Yes	Max 280 chars
`mcl.verbs`	space-separated	Yes	Subset of D7 closed vocab
`determinism`	`seedable` or `best_effort`	Yes	Compiler skills must be `seedable`
`seed_policy`	`per_intent`, `per_session`, `per_actor`	No	Default `per_intent`

on-block kind annotation

Each on-block can declare a kind that routes the synthesized step to a specialist executor model:

on verb=build
  kind = "code"
  prompt
    system="You are a code-generation assistant..."
    user="{prose}"
  end
end

Closed value set: reason (default), code, summarize, write, transform, classify, hard_reason. Skill authors can leave kind unset; the executor routes to the default reason-kind model.

Validation

Run mclc validate <path> to check a SKILL.mtx against the spec rules. The validator enforces:

All required sections present
SKILL metadata fields are populated and well-formed
Slot declarations have valid types
on-block conditions use valid syntax
Prompt blocks have system or user content
Tool/Skill URIs are well-formed
Failure mode actions are in the closed set

For core .mtx files (without a SKILL section), the validator applies ValidateCore instead.

Hashing

Run mclc hash <path> to print the canonical AST hash. This digest flows into the D11 seed and must be recomputed whenever the .mtx file changes. Comments are stripped before hashing.