skills.explain
One skill in full: its authored identity, status and provenance marker, each test that names it with the state of its latest recorded run and the command that reproduces it, its page, its doctrine and gates, every invocation by path and line, its standing and the findings about it. The file itself stays at `majordomus://skill/<id>`.
One skill in full: its authored identity, status and provenance marker, each test that names it with the state of its latest recorded run and the command that reproduces it, its page, its doctrine and gates, every invocation by path and line, its standing and the findings about it. The file itself stays at `majordomus://skill/<id>`.
- query
- behaviorally_verified
- module skills
- #skill
- #evidence
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_skill_explain |
| HTTP | GET /api/v1/skills/explain operationId skills.explain |
| command line | majordomus skills explain |
Schemas
The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.
input · SkillExplainInput
Which skill to explain, by its id. An id the repository does not hold is a refusal
naming what was looked for, never an empty answer.
use majordomus_cli::capability::builtin::skills::SkillExplainInput;
let input = SkillExplainInput { id: "implement".into() };
assert_eq!(input.id, "implement");| property | type | required | description |
|---|---|---|---|
| id | string | yes | The skill's id, which is also its directory name. |
JSON Schema
{
"additionalProperties": false,
"description": "Which skill to explain, by its id. An id the repository does not hold is a refusal\nnaming what was looked for, never an empty answer.\n\n```\nuse majordomus_cli::capability::builtin::skills::SkillExplainInput;\nlet input = SkillExplainInput { id: \"implement\".into() };\nassert_eq!(input.id, \"implement\");\n```",
"properties": {
"id": {
"description": "The skill's id, which is also its directory name.",
"type": "string"
}
},
"required": [
"id"
],
"title": "SkillExplainInput",
"type": "object"
}output · SkillStatus
One skill with everything derived about it.
use majordomus_cli::skill::SkillStatus;
// every fact is always present in the answer, so a client never has to tell "absent"
// from "false"; only the provenance is optional
let schema = serde_json::to_value(schemars::schema_for!(SkillStatus)).unwrap();
let required = schema["required"].as_array().unwrap();
for field in ["id", "valid", "tested", "documented", "enforced", "used", "standing"] {
assert!(required.iter().any(|f| f == field), "{field}");
}
assert!(!required.iter().any(|f| f == "provenance"));| property | type | required | description |
|---|---|---|---|
| description | string | yes | The description as authored. |
| documented | reference | yes | The documented fact. |
| enforced | reference | yes | The enforced fact. |
| findings | array | yes | The findings about this skill. |
| id | string | yes | The skill's id, which is its directory name. |
| path | string | yes | The file, repository-relative. |
| provenance | one of 2 | no | Where it came from, when it declares that. |
| standing | reference | yes | Where it stands, derived from the four. |
| status | string | yes | The lifecycle status as authored: draft, active or deprecated; unknown for a
file the index refused. |
| tested | reference | yes | The tested fact. |
| title | string | yes | The title as authored. |
| uri | string | yes | majordomus://skill/<id>. |
| used | reference | yes | The used fact. |
| valid | boolean | yes | Whether the file satisfies the skill contract, as the index judged it. |
| version | integer | yes | The version as authored. |
JSON Schema
{
"$defs": {
"ProofState": {
"description": "What the repository can say about one claim's proof, right now.\n\nOrdered from strongest to weakest, so a summary that sorts by this reads as a ranking.\n\n```\nuse majordomus_cli::evidence::ProofState;\n\nlet mut states = vec![ProofState::NotRun, ProofState::Stale, ProofState::Proven];\nstates.sort();\nassert_eq!(\n states,\n vec![ProofState::Proven, ProofState::Stale, ProofState::NotRun]\n);\n\n// the two strongest are deliberately not one state: `inputs unchanged` is the absence\n// of a known invalidation, and collapsing it into `proven` is the unaccountable badge\nassert_ne!(ProofState::Proven, ProofState::InputsUnchanged);\nassert!(ProofState::Proven < ProofState::InputsUnchanged);\nassert!(ProofState::InputsUnchanged.passing());\n```\n# Example\n\n```\nuse majordomus_cli::evidence::ProofState;\nassert!(ProofState::Proven.passing());\nassert!(!ProofState::NotRun.passing());\nassert!(!ProofState::InputsUnchanged.meaning().is_empty());\n```",
"oneOf": [
{
"const": "proven",
"description": "A passing run, and nothing has changed since it — the diff against the execution's\nown commit is empty but for the ledger. Proof of the tree in front of you.",
"type": "string"
},
{
"const": "inputs_unchanged",
"description": "A passing run, and nothing this claim names has changed since. Not proof at HEAD:\nsomething the claim does not name may have broken it.",
"type": "string"
},
{
"const": "stale",
"description": "A passing run, but something this claim names has changed since. The proof is older\nthan its subject.",
"type": "string"
},
{
"const": "failing",
"description": "The latest run of this claim's test did not pass.",
"type": "string"
},
{
"const": "not_run",
"description": "The claim names a test a runner owns, and no run of it has ever been recorded.",
"type": "string"
},
{
"const": "unrunnable",
"description": "The claim names a path no runner in this repository drives. Nothing can record it,\nso nothing can prove it this way.",
"type": "string"
},
{
"const": "no_test",
"description": "The claim names no test at all. Correct for a `planned` or `rejected` claim, and a\ndefect for any other.",
"type": "string"
}
]
},
"SkillDocumented": {
"description": "The documented fact: the page the site projects for the skill.\n\n```\nuse majordomus_cli::skill::SkillDocumented;\nlet d = SkillDocumented { documented: true, page: \"site/content/skills/implement.md\".into() };\nassert!(d.page.ends_with(\"implement.md\"));\n```",
"properties": {
"documented": {
"description": "Whether the page is a tracked file.",
"type": "boolean"
},
"page": {
"description": "Where the page is projected.",
"type": "string"
}
},
"required": [
"documented",
"page"
],
"type": "object"
},
"SkillEnforced": {
"description": "The enforced fact: the doctrine that validates skills and the gates a change to this one\nselects.\n\n```\nuse majordomus_cli::skill::SkillEnforced;\nlet e = SkillEnforced { enforced: false, doctrine: None, gates: vec![] };\nassert!(!e.enforced);\n```",
"properties": {
"doctrine": {
"description": "The rule whose validator is `skills`, when the index holds one.",
"type": [
"string",
"null"
]
},
"enforced": {
"description": "A doctrine validates skills, and a gate running the verification covers this file.",
"type": "boolean"
},
"gates": {
"description": "The CI gates a change to the skill selects whose command runs `skills verify`.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"enforced",
"gates"
],
"type": "object"
},
"SkillEvidence": {
"description": "What the evidence ledger can say about a skill's tests, as a whole: the weakest state of\nthe tests that name it, or `untested` when none does.\n\n```\nuse majordomus_cli::skill::SkillEvidence;\nassert!(SkillEvidence::Proven.current());\nassert!(SkillEvidence::InputsUnchanged.current());\nassert!(!SkillEvidence::Stale.current());\nassert!(SkillEvidence::Proven < SkillEvidence::Untested);\n```",
"oneOf": [
{
"const": "proven",
"description": "Every naming test has a passing run, and nothing but the ledger changed since.",
"type": "string"
},
{
"const": "inputs_unchanged",
"description": "Every naming test passed, and neither the test nor the skill changed since.",
"type": "string"
},
{
"const": "stale",
"description": "A passing run exists, and the test or the skill changed since.",
"type": "string"
},
{
"const": "failing",
"description": "The latest recorded run of a naming test did not pass.",
"type": "string"
},
{
"const": "not_run",
"description": "A test names the skill and no run of it was ever recorded.",
"type": "string"
},
{
"const": "unrunnable",
"description": "A test names the skill from a path no runner drives.",
"type": "string"
},
{
"const": "untested",
"description": "No test names the skill.",
"type": "string"
}
]
},
"SkillFinding": {
"description": "One thing the derivation found wrong, with the command that settles or reproduces it.\n\n```\nuse majordomus_cli::skill::{SkillFinding, SkillFindingLevel};\nlet f = SkillFinding {\n level: SkillFindingLevel::Fail,\n code: \"untested\".into(),\n skill: Some(\"implement\".into()),\n subject: \".ai/repo/skills/implement/SKILL.md\".into(),\n message: \"no test names this skill\".into(),\n reproduce: \"majordomus skills explain implement\".into(),\n};\nassert!(f.reproduce.contains(\"explain\"));\n```",
"properties": {
"code": {
"description": "A stable code: `contract`, `untested`, `unused`, `unevidenced`, `failing`,\n`undocumented`, `unenforced`, `unknown_skill_in_test`, `unknown_skill_invoked`.",
"type": "string"
},
"level": {
"$ref": "#/$defs/SkillFindingLevel",
"description": "`fail` or `warn`."
},
"message": {
"description": "What is wrong, and what to do about it.",
"type": "string"
},
"reproduce": {
"description": "The command that reproduces or settles it.",
"type": "string"
},
"skill": {
"description": "The skill concerned, when the finding is about one.",
"type": [
"string",
"null"
]
},
"subject": {
"description": "The file the finding is about, repository-relative.",
"type": "string"
}
},
"required": [
"level",
"code",
"subject",
"message",
"reproduce"
],
"type": "object"
},
"SkillFindingLevel": {
"description": "How bad a finding is: a failure refuses, a warning is reported.\n\n```\nuse majordomus_cli::skill::SkillFindingLevel;\nassert_ne!(SkillFindingLevel::Fail, SkillFindingLevel::Warn);\n```",
"oneOf": [
{
"const": "fail",
"description": "Refuses: `skills verify` exits 10 and the doctrine fails.",
"type": "string"
},
{
"const": "warn",
"description": "Reported, and does not refuse.",
"type": "string"
}
]
},
"SkillInvocation": {
"description": "One place a skill is invoked from.\n\n```\nuse majordomus_cli::skill::SkillInvocation;\nlet i = SkillInvocation {\n path: \".ai/repo/prompts/review.md\".into(),\n line: 3,\n reference: \"majordomus://skill/repo-review\".into(),\n};\nassert_eq!(i.line, 3);\n```",
"properties": {
"line": {
"description": "The 1-based line the reference is on.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"path": {
"description": "The invocation surface, repository-relative.",
"type": "string"
},
"reference": {
"description": "The reference as written.",
"type": "string"
}
},
"required": [
"path",
"line",
"reference"
],
"type": "object"
},
"SkillProvenance": {
"description": "Where a skill came from, when it was not written here first: an opaque marker into a\nledger kept outside the repository. The committed half names no source; the ledger entry\nit points at does, locally.\n\n```\nuse majordomus_cli::skill::SkillProvenance;\nlet p = SkillProvenance {\n origin: \"prior-art\".into(),\n ledger: \"import-2026-09-09#1\".into(),\n decision: \"adapted\".into(),\n};\nassert!(p.ledger.starts_with(\"import-\"));\n```",
"properties": {
"decision": {
"description": "`adapted`, `reimplemented` or `merged`.",
"type": "string"
},
"ledger": {
"description": "`import-<date>#<n>`: the entry of the local import ledger that holds the mapping.",
"type": "string"
},
"origin": {
"description": "`prior-art`: the concept was studied elsewhere before this skill was written.",
"type": "string"
}
},
"required": [
"origin",
"ledger",
"decision"
],
"type": "object"
},
"SkillStanding": {
"description": "Where a skill stands, derived from the four facts.\n\n```\nuse majordomus_cli::skill::SkillStanding;\nassert_eq!(SkillStanding::Orphan.label(), \"orphan\");\n```",
"oneOf": [
{
"const": "proven",
"description": "Active, and tested with current evidence, documented, enforced and used.",
"type": "string"
},
{
"const": "partial",
"description": "Active, named by a test and invoked, with at least one debt a warning names.",
"type": "string"
},
{
"const": "orphan",
"description": "Active, and no test names it or nothing invokes it.",
"type": "string"
},
{
"const": "invalid",
"description": "Its file does not satisfy the skill contract; one the index refused outright is listed\nhere too, so a listing never silently shrinks.",
"type": "string"
},
{
"const": "not_required",
"description": "Draft or deprecated: nothing is owed.",
"type": "string"
}
]
},
"SkillTest": {
"description": "One test that names a skill, and what the ledger says about it.\n\n```\nuse majordomus_cli::evidence::ProofState;\nuse majordomus_cli::skill::SkillTest;\nlet t = SkillTest {\n path: \"test/cases/95_skills.sh\".into(),\n test: Some(\"suite:95_skills\".into()),\n state: ProofState::NotRun,\n reproduce: Some(\"bash test/run.sh 95_skills\".into()),\n recorded_at: None,\n};\nassert_eq!(t.state, ProofState::NotRun);\n```",
"properties": {
"path": {
"description": "The test's path.",
"type": "string"
},
"recorded_at": {
"description": "When the run behind the state was recorded.",
"type": [
"string",
"null"
]
},
"reproduce": {
"description": "The command that runs it again.",
"type": [
"string",
"null"
]
},
"state": {
"$ref": "#/$defs/ProofState",
"description": "What the ledger says about its latest run, for this skill."
},
"test": {
"description": "Its identity in the ledger, when a runner owns the path.",
"type": [
"string",
"null"
]
}
},
"required": [
"path",
"state"
],
"type": "object"
},
"SkillTested": {
"description": "The tested fact: the tests that name the skill, and their weakest state.\n\n```\nuse majordomus_cli::skill::{SkillEvidence, SkillTested};\nlet t = SkillTested { state: SkillEvidence::Untested, tests: vec![] };\nassert!(!t.state.current());\n```",
"properties": {
"state": {
"$ref": "#/$defs/SkillEvidence",
"description": "The weakest state of the naming tests; `untested` when there are none."
},
"tests": {
"description": "Every test that names the skill, in path order.",
"items": {
"$ref": "#/$defs/SkillTest"
},
"type": "array"
}
},
"required": [
"state",
"tests"
],
"type": "object"
},
"SkillUsed": {
"description": "The used fact: every invocation surface that references the skill.\n\n```\nuse majordomus_cli::skill::SkillUsed;\nlet u = SkillUsed { used: false, invocations: vec![] };\nassert!(!u.used);\n```",
"properties": {
"invocations": {
"description": "Every reference, in path and line order.",
"items": {
"$ref": "#/$defs/SkillInvocation"
},
"type": "array"
},
"used": {
"description": "At least one invocation surface references the skill.",
"type": "boolean"
}
},
"required": [
"used",
"invocations"
],
"type": "object"
}
},
"description": "One skill with everything derived about it.\n\n```\nuse majordomus_cli::skill::SkillStatus;\n// every fact is always present in the answer, so a client never has to tell \"absent\"\n// from \"false\"; only the provenance is optional\nlet schema = serde_json::to_value(schemars::schema_for!(SkillStatus)).unwrap();\nlet required = schema[\"required\"].as_array().unwrap();\nfor field in [\"id\", \"valid\", \"tested\", \"documented\", \"enforced\", \"used\", \"standing\"] {\n assert!(required.iter().any(|f| f == field), \"{field}\");\n}\nassert!(!required.iter().any(|f| f == \"provenance\"));\n```",
"properties": {
"description": {
"description": "The description as authored.",
"type": "string"
},
"documented": {
"$ref": "#/$defs/SkillDocumented",
"description": "The documented fact."
},
"enforced": {
"$ref": "#/$defs/SkillEnforced",
"description": "The enforced fact."
},
"findings": {
"description": "The findings about this skill.",
"items": {
"$ref": "#/$defs/SkillFinding"
},
"type": "array"
},
"id": {
"description": "The skill's id, which is its directory name.",
"type": "string"
},
"path": {
"description": "The file, repository-relative.",
"type": "string"
},
"provenance": {
"anyOf": [
{
"$ref": "#/$defs/SkillProvenance"
},
{
"type": "null"
}
],
"description": "Where it came from, when it declares that."
},
"standing": {
"$ref": "#/$defs/SkillStanding",
"description": "Where it stands, derived from the four."
},
"status": {
"description": "The lifecycle status as authored: `draft`, `active` or `deprecated`; `unknown` for a\nfile the index refused.",
"type": "string"
},
"tested": {
"$ref": "#/$defs/SkillTested",
"description": "The tested fact."
},
"title": {
"description": "The title as authored.",
"type": "string"
},
"uri": {
"description": "`majordomus://skill/<id>`.",
"type": "string"
},
"used": {
"$ref": "#/$defs/SkillUsed",
"description": "The used fact."
},
"valid": {
"description": "Whether the file satisfies the skill contract, as the index judged it.",
"type": "boolean"
},
"version": {
"description": "The version as authored.",
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"id",
"uri",
"title",
"description",
"status",
"version",
"path",
"valid",
"tested",
"documented",
"enforced",
"used",
"standing",
"findings"
],
"title": "SkillStatus",
"type": "object"
}Policies
- benchmark
- required — a target on every transport the exposure declares; the cases are the input type's
- cache
- disabled — every call runs the handler
Benchmark targets
Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.
| transport | state | cases | targets |
|---|---|---|---|
| direct | covered | 1 | first-skill |
| mcp | covered | 1 | first-skill |
| http | covered | 1 | first-skill |