---
name: matrixone-docs
description: |
  Use when the user asks about MatrixOne SQL syntax, built-in functions, operators,
  MySQL compatibility, or needs to verify MatrixOne dialect-specific behavior.
  Also use when a run_sql tool returns an error that may be dialect-related, when
  the SQL being written is not standard/common MySQL SQL, or when the user mentions
  MO documentation, MO syntax, or MatrixOne docs lookup.

  Trigger phrases: "MatrixOne 文档", "MO 文档", "查 MatrixOne 语法", "search matrixone docs",
  "MatrixOne 函数", "MO SQL 语法", "MatrixOne operator", "MO docs".
---

# MatrixOne Docs Skill

Search and read MatrixOne official SQL documentation from the terminal.

## Quick Start

```bash
# Set version (optional, defaults to 3.0.13)
export MO_DOCS_VERSION="3.0.13"

# Fetch index files (one-time per version)
bash skills/matrixone-docs/scripts/fetch-index.sh

# Search for a keyword
bash skills/matrixone-docs/scripts/search-docs.sh "DATE_FORMAT"

# Search with filters
bash skills/matrixone-docs/scripts/search-docs.sh "JOIN" --kind sql --limit 5

# Read a document by path
bash skills/matrixone-docs/scripts/read-doc.sh "MatrixOne/Reference/Functions-and-Operators/date-and-time-functions/date-format/"

# Read with pagination
bash skills/matrixone-docs/scripts/read-doc.sh "MatrixOne/Reference/SQL-Reference/Data-Definition-Language/create-table/" --cursor 0 --limit 500
```

## When to Use

- User asks about MatrixOne SQL syntax or behavior
- User needs to check MySQL compatibility of a specific feature
- User asks about a MatrixOne built-in function or operator
- User encounters a `run_sql` error or SQL execution failure, especially when the error may be dialect-related
- The SQL being written uses syntax, functions, or operators that are not standard MySQL or look MatrixOne-specific

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/fetch-index.sh` | Download and cache index files from docs.matrixorigin.cn |
| `scripts/search-docs.sh` | Search cached index by keyword with optional kind filter |
| `scripts/read-doc.sh` | Fetch and display a documentation page by path |

## Version Configuration

The version can be set via:

1. `MO_DOCS_VERSION` environment variable (highest priority)
2. `--version` flag on each script
3. Default: `3.0.13`

Index files are cached per version under `skills/matrixone-docs/cache/v{version}/`.

## Common Mistakes

- **Searching before fetching**: `search-docs.sh` / `read-doc.sh` require cached indexes. Run `fetch-index.sh` first for each new version.
- **Wrong version format**: version must be `x.y.z` (e.g. `3.0.13`). `3.0` or `latest` will fail.
- **Using full URL instead of doc_path**: `read-doc.sh` expects the path segment only (e.g. `MatrixOne/Reference/.../date-format/`), not the full `https://...` URL.
- **Forgetting `--kind` filter**: searching a common keyword like `SELECT` without `--kind sql` may return functions and operators too. Use `--kind` to narrow results.

## Document Kinds

| Kind | Index File | Description |
|------|-----------|-------------|
| `sql` | llms-sql.txt | SQL reference (DDL, DML, etc.) |
| `function` | llms-func.txt | Built-in functions |
| `operator` | llms-op.txt | Operators |
| `all` | (all three) | Search across all kinds |