A repository has procedures that its workers, human and machine, are supposed to follow: how a review is done here, how a change is carried out, how the site is deployed. They live in somebody's head, in a wiki nobody updates, or pasted into a provider's own configuration file where the next tool cannot read them.
setup: installed-skill
given:
- 'a repository whose skills section holds one skill directory with SKILL.md and one example, tracked in git'
steps:
- id: list
run: ['skills', 'list']
note: 'the inventory is the directory: what is tracked is what is listed'
expect:
exit: 0
stdout_contains: ['^release-notes +active +v1 ']
- id: read-one
run: ['skills', 'show', 'release-notes']
note: 'the canonical path, then the file as written — the procedure, not a paraphrase'
expect:
exit: 0
stdout_contains: ['^\.ai/repo/skills/release-notes/SKILL\.md$', '^# Procedure$']
- id: machine-readable
run: ['skills', 'show', 'release-notes', '--json']
note: 'the same skill for a program: metadata, provenance, examples and the body'
expect:
exit: 0
stdout_contains: ['"uri":"majordomus://skill/release-notes"', '"path":".ai/repo/skills/release-notes/SKILL.md"', '"valid":true']
- id: check
run: ['skills', 'check']
note: 'a clean result states what it examined; a repository with no skills is reported, never passed'
expect:
exit: 0
stdout_contains: ['^OK skill', 'skills: 1 discovered']
- id: refuse-unknown
run: ['skills', 'show', 'nosuch']
note: 'a skill that does not exist is named, with the command that lists what does'
expect:
exit: 12
stdout_contains: ["no skill 'nosuch'", 'majordomus skills list']
then:
- 'the listing, the catalogue the site renders and the resources the MCP server serves all come from the same discovery'
- 'adding a skill is adding its directory; removing it removes the skill from every surface'
Each procedure is one directory under the layer's skills section holding SKILL.md, discovered because the file exists. skills list is the inventory, skills show is the procedure as written with the path it came from, and skills check reports what it examined — skills, examples and references — so a pass is evidence rather than a word. The same catalogue is what the website's skills pages and the MCP resources are projected from, so no surface keeps its own list.
-
the inventory is the directory: what is tracked is what is listed
release-notes active v1 Write the release notes for a tagged version from the ledger and the closed issues, never from memory.
- exit 0
- stdout_contains /^release-notes +active +v1 /
-
the canonical path, then the file as written — the procedure, not a paraphrase
.ai/repo/skills/release-notes/SKILL.md
---
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.
- exit 0
- stdout_contains /^\.ai/repo/skills/release-notes/SKILL\.md$/
- stdout_contains /^# Procedure$/
-
the same skill for a program: metadata, provenance, examples and the body
{"id":"release-notes","uri":"majordomus://skill/release-notes","title":"Release notes","description":"Write the release notes for a tagged version from the ledger and the closed issues, never from memory.","status":"active","version":1,"tags":["release","documentation"],"related":[],"inputs":["the tag being released and the previous tag"],"outputs":["a release-notes section per closed issue, each naming its evidence"],"path":".ai/repo/skills/release-notes/SKILL.md","sha256":"<sha><hash16>2743ea3a","examples":[".ai/repo/skills/release-notes/examples/notes-for-a-tag.md"],"valid":true,"body":"# Purpose\n\nTurn what the ledger and the plan record into the notes a reader of the tag needs.\n\n# Procedure\n\n1. List the issues closed between the two tags with `majordomus plan list`.\n2. For each, quote its outcome and the evidence attached to it.\n3. Refuse to describe a change that no closed issue records.\n\n# Output\n\nOne section per issue: title, what changed, the evidence, in plan order.\n"}
- exit 0
- stdout_contains /"uri":"majordomus://skill/release-notes"/
- stdout_contains /"path":".ai/repo/skills/release-notes/SKILL.md"/
- stdout_contains /"valid":true/
-
a clean result states what it examined; a repository with no skills is reported, never passed
OK skill 1 skill(s) — every one parses, matches its directory and carries its sections
OK skill 1 reference(s) — every related id and every example resolves
skills: 1 discovered, 1 valid; examples: 1; references: 1 checked; failures: 0
- exit 0
- stdout_contains /^OK skill/
- stdout_contains /skills: 1 discovered/
-
a skill that does not exist is named, with the command that lists what does
majordomus: no skill 'nosuch' (.ai/repo/skills/nosuch/SKILL.md); try: majordomus skills list
- exit 12
- stdout_contains /no skill 'nosuch'/
- stdout_contains /majordomus skills list/
The chain from this page to the code: the use case names commands, rules and claims; each rule is dispatched from the registry and each claim names the test that proves it; the scenario above executed the commands. Nothing in this chain is prose about intent.
Computed from what they share: claims, rules, commands, category, applications. Nobody maintains this list.