Magisterium AI exposes the following skills through the A2A protocol. Specify the skill to use via metadata.skillId on the message. If skillId is omitted, catholic_qa is used as the default.

All skills are invoked via the message/send JSON-RPC method.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "unique-id",
      "kind": "message",
      "parts": [{ "kind": "text", "text": "your query here" }],
      "metadata": { "skillId": "document_search" }
    }
  }
}

Responses always come back as a Task (kind: "task") with status.state: "completed" and one or more artifacts. Each artifact has a unique artifactId, a skill-specific name, and one or more parts (text, data, or file).

catholic_qa

Ask a natural-language question and receive a cited, long-form answer. This is the most capable (and most resource-intensive) skill — it runs against the same model that powers magisterium.com.

Input: a single text part with the question.

Artifact: name: "catholic_qa_response" containing:

• A text part with the full answer.
• A data part with citations (when any sources were used).
• A data part with related_questions (when the model returns suggestions).

{
  "artifactId": "art_...",
  "name": "catholic_qa_response",
  "parts": [
    { "kind": "text", "text": "The Catholic Church teaches..." },
    { "kind": "data", "data": { "citations": [ /* ... */ ] } },
    { "kind": "data", "data": { "related_questions": [ /* ... */ ] } }
  ]
}

catholic_qa uses a stricter rate-limit variant than the other skills. See API Reference → Rate Limits.

document_search

Retrieve document references that match a semantic query against the Magisterium knowledgebase.

Input: a single text part with the query.

Artifact: name: "search_results" with a single data part:

{
  "artifactId": "art_...",
  "name": "search_results",
  "parts": [
    {
      "kind": "data",
      "data": {
        "results": [
          { "id": "12345", "url": "https://...", "title": "Lumen Gentium" }
        ]
      }
    }
  ]
}

Use the id field from a result to call document_fetch for the full text.

document_fetch

Retrieve the full text and metadata of a document by its ID. This skill accepts a data part instead of a text part:

{
  "parts": [{ "kind": "data", "data": { "id": "12345" } }]
}

If the caller sends a text part, the handler falls back to treating it as the document ID.

Artifact: name: "document" with two parts:

• A text part containing the document body.
• A data part with { id, title, author, ref }.

If the document is not found, the artifact contains a single text part reading "Document not found.".

liturgical_readings

Get Catholic Mass readings for a given date. Accepts a natural-language date query — e.g. "today", "next Sunday", or "Easter Sunday 2026".

Input: a single text part with the date query.

Artifact: name: "mass_readings" with a single text part containing the formatted readings. If no readings are available for the requested date, the part reads "No mass readings found.".

saints_of_the_day

Look up the saints commemorated on a given date from the Roman Martyrology.

Input: a data part with an absolute date, or a text part treated as a date query:

{
  "parts": [{ "kind": "data", "data": { "date": "2026-03-19" } }]
}

Artifact: name: "martyrology" with a single text part containing the formatted martyrology entry. Missing dates return "No martyrology data found.".

The five skills below are directory lookups. Each accepts a natural-language query (as a text part or a data.query field) plus an optional canonical ID, and returns a structured profile inside a single data part. If neither query nor a canonical ID is provided, the request is rejected with INVALID_PARAMS (-32602).

When the query cannot be resolved, the artifact contains a data part of the form { "error": "not_found", "query": "...", "hint"?: "..." } instead of a profile. The task itself still completes successfully — not_found is a normal lookup result, not a protocol error.

saint_lookup

Look up a saint, blessed, venerable, or servant of God from the cd_saints directory (~12,500 figures).

Input: data.query (e.g. "Therese of Lisieux") or data.saint_id (canonical primary key, e.g. "jerome"). A bare text part is accepted as query.

{
  "parts": [{ "kind": "data", "data": { "query": "Catherine of Siena" } }]
}

Artifact: name: "saint_profile" with a single data part containing the canonical profile — saint_id, primary_name, canonical_status, vocation, image_url, learn_more_url, life and death, feast day, canonization cause, patronage, iconography, biography, and (if multiple candidates were found) an alternates array.

person_lookup

Look up a Catholic clergy figure (bishop, cardinal, archbishop, etc.) from the cd_persons (living, ~3,500) and cd_persons_historical (~2,200) directories. Popes are exposed via the separate pope_lookup skill.

Input: data.query (e.g. "Cardinal Tagle") or data.person_id (canonical primary key). A bare text part is accepted as query.

{
  "parts": [{ "kind": "data", "data": { "query": "Cardinal Tagle" } }]
}

Artifact: name: "person_profile" with a single data part containing the canonical profile — person_id, source_table, primary_name, current_position, image_url, coat_of_arms_url, ordination and consecration dates, cardinal elevation, episcopal lineage, education, motto, and any alternates.

If the query resolves only to a pope, the response is { "error": "not_found", "hint": "Top match looks like a pope; try get_pope." }.

pope_lookup

Look up a pope from the cd_popes directory (267 figures).

Input: data.query (e.g. "Pope Francis", "John Paul II") or data.pope_id (canonical primary key, e.g. "benedict-xvi"). A bare text part is accepted as query.

{
  "parts": [{ "kind": "data", "data": { "query": "John Paul II" } }]
}

Artifact: name: "pope_profile" with a single data part containing the canonical papal profile — pope_id, primary_name, papal_name, ordinal, pope_title, image_url, coat_of_arms_url, birth_name, origin, pontificate, beatification and canonization status, and any alternates.

If the query resolves only to a non-pope clergy member, the response is { "error": "not_found", "hint": "Top match looks like a non-pope clergy member; try get_person." }.

diocese_lookup

Look up an ecclesiastical jurisdiction (diocese, archdiocese, eparchy, etc.) from the dioceses directory (~3,200 jurisdictions worldwide).

Input: data.query (e.g. "Archdiocese of Manila") or data.source_code (canonical primary key, e.g. "dmaml"). A bare text part is accepted as query.

{
  "parts": [{ "kind": "data", "data": { "query": "Archdiocese of Manila" } }]
}

Artifact: name: "diocese_profile" with a single data part containing directory metadata (source_code, primary_name, jurisdiction_type, rite, country, region_primary, state, city, metropolitan, depends_on, province, cathedral, patron_saint, area, erected, elevated, official_website, image_url, current_bishop) plus:

• recent_statistics — up to 5 years of headline figures (catholics, total population, percent Catholic, total priests, parishes, baptisms, seminarians).
• latest_financials — the most recent fiscal year's headline metrics (total revenue, total expenses, net assets, total assets, surplus/deficit) when available, with currency.
• alternates — when multiple candidates matched.

For multi-year trend analysis, use diocese_statistics_lookup instead.

diocese_statistics_lookup

Return the full yearly statistics time-series for a diocese — all 19 metrics tracked in diocese_statistics.

Input: data.query or data.source_code (one is required), plus optional inclusive bounds:

{
  "parts": [{
    "kind": "data",
    "data": {
      "source_code": "dmaml",
      "start_year": 2010,
      "end_year": 2024
    }
  }]
}

Artifact: name: "diocese_statistics_time_series" with a single data part containing source_code, diocese_name, year_range: { start, end }, and a rows array. Each row carries 19 metrics for one year: catholics, total_population, percent_catholic, diocesan_priests, religious_priests, total_priests, catholics_per_priest, permanent_deacons, male_religious, female_religious, parishes, area_km2, churches_or_stations, diocesan_priests_ordained, religious_priests_ordained, seminarians, educational_institutes, charitable_institutes, baptisms.