Intended audience: USERS
AO Platform: 5.0
Overview
The ao-mcp-query skill is a Claude-side skill that governs how Claude answers data questions using the AO MCP Server tools. It is not part of the server itself — it runs within the Claude client (Cowork or Claude Code) and provides a structured workflow for querying ontology data via natural language.
What It Does
When a user asks a data question (e.g., "how many meters are there?", "show all bills greater than $50"), the skill orchestrates the full query lifecycle: ontology selection, natural language to Semantic SQL conversion, ambiguity resolution, query execution, and optional Chart.js visualization — all while minimizing token usage.
Guiding Principles
-
Ontology agnostic: Works across any ontology without assuming domain-specific names. Schema is always discovered incrementally.
-
Token efficient: Never loads the full schema. Uses incremental tools (`list-msos`, `describe-mso`, `search-schema`) instead of `export-ontology-schema`.
-
Fail gracefully: When something goes wrong, the skill stops and explains the error to the user rather than silently trying alternatives.
-
Visualization on request: Charts are never generated automatically — Claude always asks the user first.
-
User-driven decisions: If a query fails or returns unexpected results, the skill asks the user before pivoting.
Query Workflow
The skill follows a five-step workflow for each data question:
-
Step 1 — Identify the Ontology. If only one ontology exists, use it. If multiple exist, call `list-ontologies` and let the user choose.
-
Step 2 — Generate Semantic SQL. Call `nlq-to-semantic-sql` with the user's question. The tool supports three query modes: Controlled (strict matching), Balanced (default — moderate flexibility), and Freeform (liberal interpretation). If ambiguity is returned instead of SQL, the skill presents options to the user and re-calls with their selection. If the tool errors out, the skill explains the failure and offers to attempt manual SQL construction — only with user confirmation.
-
Step 3 — Execute the Query. Run the generated SQL via `execute-semantic-sql`. On failure or empty results, the skill explains what happened and asks the user how to proceed.
-
Step 4 — Schema Lookup (only if needed). If SQL or results are unclear, use incremental schema tools to verify column names, sample values, or relationships.
-
Step 5 — Offer Visualization. After presenting results as a plain English summary, the skill offers to generate a Chart.js visualization. Chart type is selected based on data shape (e.g., pie for small category counts, line for time series, bar for comparisons).
Ambiguity Resolution
When `nlq-to-semantic-sql` detects ambiguity, the skill handles two types:
-
MSO ambiguity: The question matches multiple entities (e.g., "financial entities" could mean Bills, Payments, or Contract Account). The skill presents options and recalls with the user's choice.
-
MSO_PROPERTY ambiguity: The question matches multiple properties within an entity (e.g., "$50" could refer to Final Balance, Balance Forward, or Original Balance). Same resolution pattern.
The skill loops up to 3 times. If ambiguity persists, it suggests rephrasing the question or switching query modes.
Error Handling
On any failure, the skill follows a strict protocol: state what failed, explain in plain English, offer 1–2 specific next steps, and wait for user confirmation. It never silently retries or modifies a query without the user's go-ahead.
Installation
The ao-mcp-query skill is bundled with the AO MCP Server plugin for Cowork. For Claude Code, the skill files are located under claude/skills/ao-mcp-query/ in the project repository. The skill is activated automatically when the ao-mcp-server tools are available, and the user asks a data question.
Video
-
Adding the ao-mcp-query.skill
Download
Contact App Orchid | Disclaimer