Query MatrixOne Documentation with AI Agent

The MatrixOne documentation lookup skill lets an AI Agent search the official MatrixOne documentation from a terminal. It is useful for checking SQL syntax, built-in functions, operators, MySQL compatibility, and MatrixOne-specific behavior.

Download the Files

We recommend downloading the complete ZIP archive. Extract it to preserve the original directory structure of all skill files:

Download matrixone-docs-main.zip

You can also download individual files:

File	Purpose
SKILL.md	Codex skill instructions
README.md	Standalone usage instructions
fetch-index.sh	Download and cache LLM index files
search-docs.sh	Search cached indexes
read-doc.sh	Read a document by its doc_path

The complete directory contains:

matrixone-docs-main/
├── README.md
├── SKILL.md
└── scripts/
    ├── fetch-index.sh
    ├── read-doc.sh
    └── search-docs.sh

If you install it in the Codex skill directory, use $CODEX_HOME/skills/matrixone-docs/.

Usage

Before using a document version for the first time, download its indexes:

export MO_DOCS_VERSION="3.0.13"
bash scripts/fetch-index.sh
bash scripts/search-docs.sh "CREATE TABLE" --kind sql --limit 5
bash scripts/read-doc.sh "MatrixOne/Reference/Functions-and-Operators/Datetime/date-format/"

Version Configuration

The version can be specified with the MO_DOCS_VERSION environment variable, a --version argument, or the default value 3.0.13. The version must use the x.y.z format, such as 3.0.13; latest is not supported.

Indexes are cached under cache/v{version}/, including llms-sql.txt, llms-func.txt, and llms-op.txt.

Example for an Agent

When a user asks whether MatrixOne supports CLUSTER BY in CREATE TABLE:

1. bash scripts/fetch-index.sh --version 3.0.13
2. bash scripts/search-docs.sh "CLUSTER BY" --kind sql --version 3.0.13
3. Pass the returned doc_path to read-doc.sh
4. Answer using the official documentation and include its path

Source Files

SKILL.md

---
name: matrixone-docs
description: |
  Use when the user asks about MatrixOne SQL syntax, built-in functions, operators,
  MySQL compatibility, or MatrixOne dialect-specific behavior. Also use when a
  run_sql error may be dialect-related or the user asks to search MatrixOne docs.

  Trigger phrases: "MatrixOne docs", "MO docs", "search MatrixOne syntax",
  "MatrixOne functions", "MO SQL syntax", "MatrixOne operator".
---

# MatrixOne Docs Skill

Search and read the official MatrixOne SQL documentation from the terminal.

## Quick Start

```bash
export MO_DOCS_VERSION="3.0.13"
bash skills/matrixone-docs/scripts/fetch-index.sh
bash skills/matrixone-docs/scripts/search-docs.sh "DATE_FORMAT"
bash skills/matrixone-docs/scripts/read-doc.sh "MatrixOne/Reference/Functions-and-Operators/date-and-time-functions/date-format/"
```

## When to Use

- The user asks about MatrixOne SQL syntax or behavior.
- The user needs to check MySQL compatibility.
- The user asks about a MatrixOne function or operator.
- A SQL execution error may be caused by MatrixOne dialect differences.

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/fetch-index.sh` | Download and cache index files |
| `scripts/search-docs.sh` | Search cached indexes |
| `scripts/read-doc.sh` | Read a documentation page by path |

## Version Configuration

Set `MO_DOCS_VERSION`, pass `--version`, or use the default `3.0.13`. Indexes are cached under `skills/matrixone-docs/cache/v{version}/`.

## Common Mistakes

- Run `fetch-index.sh` before searching or reading a new version.
- Use an `x.y.z` version such as `3.0.13`; `latest` is not supported.
- Pass a `doc_path` to `read-doc.sh`, not a full URL.
- Use `--kind sql`, `function`, or `operator` to narrow common searches.

## Document Kinds

| Kind | Index File | Description |
|------|------------|-------------|
| `sql` | llms-sql.txt | SQL reference |
| `function` | llms-func.txt | Built-in functions |
| `operator` | llms-op.txt | Operators |
| `all` | all three | Search all kinds |

fetch-index.sh

#!/usr/bin/env bash
set -euo pipefail

# Resolve skill root regardless of CWD (scripts can be invoked from repo root or elsewhere).
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
CACHE_DIR="$SKILL_DIR/cache"

usage() {
  cat <<'EOF'
Usage: fetch-index.sh [--version <x.y.z>]

Download MatrixOne documentation index files from docs.matrixorigin.cn
and cache them locally under skills/matrixone-docs/cache/v{version}/.

Environment:
  MO_DOCS_VERSION    Doc version (default: 3.0.13), overridden by --version.
EOF
  exit 0
}

VERSION="${MO_DOCS_VERSION:-3.0.13}"

while [[ $# -gt 0 ]]; do
  case "$1" in
    --version) VERSION="$2"; shift 2 ;;
    -h|--help) usage ;;
    *) echo "Unknown option: $1"; usage ;;
  esac
done

if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
  echo "Error: invalid version '$VERSION' (expected x.y.z)" >&2
  exit 1
fi

BASE_URL="https://docs.matrixorigin.cn/en/v26.${VERSION}"
DEST="$CACHE_DIR/v${VERSION}"
mkdir -p "$DEST"

KINDS=("sql" "func" "op")
NAMES=("SQL Reference" "Functions" "Operators")
FILES=("llms-sql.txt" "llms-func.txt" "llms-op.txt")

FAILED=0
for i in "${!KINDS[@]}"; do
  KIND="${KINDS[$i]}"
  NAME="${NAMES[$i]}"
  FILE="${FILES[$i]}"
  URL="${BASE_URL}/llms-${KIND}.txt"
  DEST_FILE="$DEST/$FILE"

  echo "Fetching $NAME index ($KIND) from $URL ..."
  if curl -fsSL --connect-timeout 10 --max-time 30 -o "$DEST_FILE" "$URL"; then
    LINES=$(wc -l < "$DEST_FILE" | tr -d ' ')
    echo "  OK: $LINES lines -> $DEST_FILE"
  else
    echo "  FAILED: could not fetch $URL" >&2
    FAILED=1
  fi
done

if [[ $FAILED -eq 1 ]]; then
  echo ""
  echo "Some indexes failed to download. Check your network or the version." >&2
  echo "URL pattern: $BASE_URL/llms-{kind}.txt" >&2
  exit 1
fi

echo ""
echo "Done. Indexes cached at $DEST/"
echo "Run: bash skills/matrixone-docs/scripts/search-docs.sh <keyword>"

search-docs.sh

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
CACHE_DIR="$SKILL_DIR/cache"

usage() {
  cat <<'EOF'
Usage: search-docs.sh <query> [--kind all|sql|function|operator] [--limit <n>] [--version <x.y.z>]

Search cached MatrixOne documentation indexes. Requires fetch-index.sh to have
been run first for the requested version.

Environment:
  MO_DOCS_VERSION    Doc version (default: 3.0.13), overridden by --version.
EOF
  exit 0
}

QUERY=""
KIND="all"
LIMIT=8
VERSION="${MO_DOCS_VERSION:-3.0.13}"

while [[ $# -gt 0 ]]; do
  case "$1" in
    --kind)   KIND="$2"; shift 2 ;;
    --limit)  LIMIT="$2"; shift 2 ;;
    --version) VERSION="$2"; shift 2 ;;
    -h|--help) usage ;;
    *) QUERY="$1"; shift ;;
  esac
done

if [[ -z "$QUERY" ]]; then
  echo "Error: query is required" >&2
  usage
fi

if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
  echo "Error: invalid version '$VERSION'" >&2
  exit 1
fi

case "$KIND" in
  all|sql|function|operator) ;;
  *) echo "Error: kind must be one of all, sql, function, operator" >&2; exit 1 ;;
esac

INDEX_DIR="$CACHE_DIR/v${VERSION}"
KIND_MAP='sql:llms-sql.txt function:llms-func.txt operator:llms-op.txt'

FILES_TO_SEARCH=()
if [[ "$KIND" == "all" ]]; then
  FILES_TO_SEARCH=("$INDEX_DIR/llms-sql.txt" "$INDEX_DIR/llms-func.txt" "$INDEX_DIR/llms-op.txt")
else
  KIND_KEY="$KIND"
  case "$KIND" in
    sql)      FILENAME="llms-sql.txt" ;;
    function) FILENAME="llms-func.txt" ;;
    operator) FILENAME="llms-op.txt" ;;
  esac
  FILES_TO_SEARCH=("$INDEX_DIR/$FILENAME")
fi

for f in "${FILES_TO_SEARCH[@]}"; do
  if [[ ! -f "$f" ]]; then
    echo "Error: index file not found: $f" >&2
    echo "Run: bash skills/matrixone-docs/scripts/fetch-index.sh --version $VERSION" >&2
    exit 1
  fi
done

# Parse index lines format:
# - [Title](URL) [compatibility]: optional summary
# Match against lowercase query in title, summary, compatibility.
QUERY_LC=$(echo "$QUERY" | tr '[:upper:]' '[:lower:]')
COUNT=0

search_file() {
  local file="$1"
  local tag="$2"
  while IFS= read -r line; do
    [[ $COUNT -ge $LIMIT ]] && return
    # Only process lines starting with "- [title](url) [compat]"
    [[ "$line" == "- ["* ]] || continue

    # Extract title: everything between "- [" and "]("
    local title
    title=$(echo "$line" | sed -n 's/^- \[\(.*\)\](\(.*\)) \[\(.*\)\].*$/\1/p')
    [[ -n "$title" ]] || continue

    # Extract url: between "](" and ")"
    local url
    url=$(echo "$line" | sed -n 's/^- \[.*\](\(.*\)) \[.*\].*$/\1/p')
    [[ -n "$url" ]] || continue

    # Extract compatibility: between "] [" and "]"
    local compat
    compat=$(echo "$line" | sed -n 's/^- \[.*\](.*) \[\(.*\)\].*$/\1/p')

    # Extract optional summary: after the compat bracket
    local summary
    summary=$(echo "$line" | sed -n 's/^- \[.*\](.*) \[.*\]: \(.*\)$/\1/p')

    local haystack
    haystack=$(echo "$title $compat $summary" | tr '[:upper:]' '[:lower:]')
    if [[ "$haystack" != *"$QUERY_LC"* ]]; then
      continue
    fi

    # Extract doc_path from URL: strip https://docs.matrixorigin.cn/en/v26.x.y.z/
    local prefix="https://docs.matrixorigin.cn/en/v26.${VERSION}/"
    local doc_path="${url#$prefix}"

    echo "---"
    echo "title:       $title"
    echo "kind:        $tag"
    echo "compatibility: $compat"
    [[ -n "$summary" ]] && echo "summary:     $summary"
    echo "url:         $url"
    echo "doc_path:    $doc_path"
    COUNT=$((COUNT + 1))
  done < "$file"
}

if [[ "$KIND" == "all" ]]; then
  search_file "${FILES_TO_SEARCH[0]}" "sql"
  search_file "${FILES_TO_SEARCH[1]}" "function"
  search_file "${FILES_TO_SEARCH[2]}" "operator"
else
  search_file "${FILES_TO_SEARCH[0]}" "$KIND"
fi

if [[ $COUNT -eq 0 ]]; then
  echo "No results found for '$QUERY' (kind=$KIND, version=$VERSION)" >&2
  exit 1
fi

read-doc.sh

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
CACHE_DIR="$SKILL_DIR/cache"

usage() {
  cat <<'EOF'
Usage: read-doc.sh <doc_path> [--cursor <n>] [--limit <n>] [--version <x.y.z>]

Read a MatrixOne documentation page by its doc_path. The doc_path is obtained
from search-docs.sh output.

Environment:
  MO_DOCS_VERSION    Doc version (default: 3.0.13), overridden by --version.
EOF
  exit 0
}

DOC_PATH=""
CURSOR=0
LIMIT=8000
VERSION="${MO_DOCS_VERSION:-3.0.13}"

while [[ $# -gt 0 ]]; do
  case "$1" in
    --cursor)  CURSOR="$2"; shift 2 ;;
    --limit)   LIMIT="$2"; shift 2 ;;
    --version) VERSION="$2"; shift 2 ;;
    -h|--help) usage ;;
    *) DOC_PATH="$1"; shift ;;
  esac
done

if [[ -z "$DOC_PATH" ]]; then
  echo "Error: doc_path is required" >&2
  usage
fi

if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
  echo "Error: invalid version '$VERSION'" >&2
  exit 1
fi

if [[ "$CURSOR" -lt 0 ]]; then
  echo "Error: cursor must be >= 0" >&2
  exit 1
fi

if [[ "$LIMIT" -lt 1 || "$LIMIT" -gt 20000 ]]; then
  echo "Error: limit must be between 1 and 20000" >&2
  exit 1
fi

# Build URL. doc_path may or may not have a trailing slash; strip it for the .md append.
DOC_PATH_CLEAN="${DOC_PATH%/}"
URL="https://docs.matrixorigin.cn/en/v26.${VERSION}/${DOC_PATH_CLEAN}.md"

TMPFILE=$(mktemp /tmp/mo-docs-read.XXXXXX)
trap 'rm -f "$TMPFILE"' EXIT

echo "Fetching $URL ..." >&2
if ! curl -fsSL --connect-timeout 10 --max-time 30 -o "$TMPFILE" "$URL"; then
  echo "Error: failed to fetch $URL" >&2
  exit 1
fi

TOTAL_CHARS=$(wc -m < "$TMPFILE" | tr -d ' ')

if [[ "$CURSOR" -ge "$TOTAL_CHARS" ]]; then
  echo "Error: cursor $CURSOR exceeds total chars $TOTAL_CHARS" >&2
  exit 1
fi

# Extract the requested window.
END=$((CURSOR + LIMIT))
if [[ "$END" -gt "$TOTAL_CHARS" ]]; then
  END="$TOTAL_CHARS"
fi

CONTENT=$(tail -c +$((CURSOR + 1)) "$TMPFILE" | head -c $((END - CURSOR)))
RETURNED=${#CONTENT}

NEXT_CURSOR=0
if [[ "$END" -lt "$TOTAL_CHARS" ]]; then
  NEXT_CURSOR="$END"
fi

echo "doc_path:       $DOC_PATH"
echo "source_url:     $URL"
echo "total_chars:    $TOTAL_CHARS"
echo "cursor:         $CURSOR"
echo "returned_chars: $RETURNED"
echo "next_cursor:    $NEXT_CURSOR"
echo "---"
echo "$CONTENT"