The repository's skills — provider-neutral procedures under the skills section — listed, shown and checked from the one catalogue every surface reads.
The repository's skills — provider-neutral procedures under the skills section — listed, shown and checked from the one catalogue every surface reads.
read-only
memory
--json
Discovery is the source class `skill` in the repository's knowledge sources, the same declaration the Rust executable indexes, so a skill exists for every interface or for none. check validates every skill against the schema-derived allow-list, its directory, its sections and its references, and prints what it examined.
Only the codes this command can produce. The full contract is on the commands index.
0ok
2usage
10contract unmet
12missing artifact
13internal error
Skills are data
A skill is a directory under the repository's skills section holding SKILL.md: front matter that satisfies the skill schema over a body that is the procedure. Nothing registers it. The source class `skill` in the knowledge sources discovers it, the same declaration the Rust executable serves it from, so list, check, the site and MCP all read one catalogue.
A skill exists because its file does
skill tracked
yes
Given this repository
# Installed, with one skill written the way a repository writes its own: a directory under
# the skills section holding SKILL.md and one example, both tracked. Nothing registers it;
# the source class `skill` in the knowledge sources is what makes it exist.
. "$FIXTURE_SETUP/installed.sh"
mkdir -p .ai/repo/skills/release-notes/examples
cat > .ai/repo/skills/release-notes/SKILL.md <<'S'
---
schema: skill/v1
id: release-notes
version: 1
title: Release notes
description: Write the release notes for a tagged version from the ledger and the closed issues, never from memory.
status: active
tags: [release, documentation]
inputs:
- the tag being released and the previous tag
outputs:
- a release-notes section per closed issue, each naming its evidence
---
# Purpose
Turn what the ledger and the plan record into the notes a reader of the tag needs.
# Procedure
1. List the issues closed between the two tags with `majordomus plan list`.
2. For each, quote its outcome and the evidence attached to it.
3. Refuse to describe a change that no closed issue records.
# Output
One section per issue: title, what changed, the evidence, in plan order.
S
cat > .ai/repo/skills/release-notes/examples/notes-for-a-tag.md <<'S'
# Notes for one tag
```text
Apply the release-notes skill to the range v0.1.0..v0.2.0.
```
S
git add .ai/repo/skills && git commit -qm "a skill" >/dev/null
Run
$ majordomus skills list
Output contains
release-notes
active
v1
exit0
The listing is derived from discovery, not from a registry: adding the directory and tracking it is the whole registration.
What check examined
skill tracked
yes
Given this repository
# Installed, with one skill written the way a repository writes its own: a directory under
# the skills section holding SKILL.md and one example, both tracked. Nothing registers it;
# the source class `skill` in the knowledge sources is what makes it exist.
. "$FIXTURE_SETUP/installed.sh"
mkdir -p .ai/repo/skills/release-notes/examples
cat > .ai/repo/skills/release-notes/SKILL.md <<'S'
---
schema: skill/v1
id: release-notes
version: 1
title: Release notes
description: Write the release notes for a tagged version from the ledger and the closed issues, never from memory.
status: active
tags: [release, documentation]
inputs:
- the tag being released and the previous tag
outputs:
- a release-notes section per closed issue, each naming its evidence
---
# Purpose
Turn what the ledger and the plan record into the notes a reader of the tag needs.
# Procedure
1. List the issues closed between the two tags with `majordomus plan list`.
2. For each, quote its outcome and the evidence attached to it.
3. Refuse to describe a change that no closed issue records.
# Output
One section per issue: title, what changed, the evidence, in plan order.
S
cat > .ai/repo/skills/release-notes/examples/notes-for-a-tag.md <<'S'
# Notes for one tag
```text
Apply the release-notes skill to the range v0.1.0..v0.2.0.
```
S
git add .ai/repo/skills && git commit -qm "a skill" >/dev/null
Run
$ majordomus skills check
Output contains
OK skill
skills: 1 discovered, 1 valid
references: 1 checked
exit0
A clean result states what it examined — skills, examples, references — so that a pass over nothing cannot look like a pass.
Asking for one that does not exist
skill tracked
no
Given this repository
# A repository with Majordomus installed and projections generated, and one commit of work.
"$MJ" init >/dev/null
"$MJ" update >/dev/null
mkdir -p lib docs
echo a > lib/a
echo d > docs/d
git add . && git commit -qm base
Run
$ majordomus skills show nosuch
Output contains
no skill
skills list
exit12
Exit 12 is MISSING_ARTIFACT, and the message names the command that lists what does exist.
Reference
The repository's skills: provider-neutral procedures for one bounded kind of work each,
under the layer's skills section. Read-only.
A skill is a directory .ai/repo/skills/<id>/ holding SKILL.md — YAML front matter
satisfying share/schemas/majordomus/skill/skill.v1.schema.json over a Markdown body that is the procedure —
and optionally examples/*.md. Nothing registers it. The source class skill in
.ai/repo/knowledge/sources.yaml discovers it, and that is the same declaration the
Rust executable indexes, so a skill exists for skills list, for doctor, for the
website and for MCP (majordomus://skill/<id>), or for none of them. See
SCHEMAS.md for the file contract.
majordomus skills list [--json] every skill: id, status, version, descriptionmajordomus skills show <id> [--json] the repository-relative path, then the file as writtenmajordomus skills check [--json] validate every skill and every reference it makes
list prints one line per discovered skill in discovery order, invalid ones included
(a listing that silently shrank would hide the file that needs fixing). --json adds
the URI, tags, related ids, inputs, outputs, the path, the content hash and the tracked
examples.
show prints the path on the first line and the file below it; --json adds the
body as a field. An id that is not a skill exits 12 and names skills list.
check validates every skill against the allow-list generated from the schema (no
unknown key), schema: skill/v1, an integer version, a status from the closed
set, an id equal to the directory name, non-empty # Purpose, # Procedure and
# Output sections; refuses two skills claiming one id, two skills whose descriptions
do not tell them apart, a related id that names no skill, and an example without a
level-one heading. Descriptions are compared folded to lower case, with runs of
whitespace collapsed and trailing sentence punctuation dropped, so the difference has
to be in what a description says rather than in how it is typed. Every finding names the file and
every reason. It ends with the counts of what it examined — skills, examples,
references — and exits 10 on any failure. A repository with no skills is a WARN,
never a pass over nothing. An absent allow-list (share/allow/skill.txt, a distribution
that was not generated) is 13, naming majordomus generate allow.
doctor and watch run the same examination through the doctrine
majordomus.skill-integrity; scripts/generate-site-data reads the same catalogue and
refuses to build the site from a skill that does not validate.
$ majordomus skills checkOK skill 1 skill(s) — every one parses, matches its directory and carries its sectionsOK skill 5 reference(s) — every related id and every example resolvesskills: 1 discovered, 1 valid; examples: 5; references: 5 checked; failures: 0
Evidence
Every case below runs in CI on Linux and macOS. The site refuses to build if a public command has no behavioural case, no negative case, or no demonstration.