Agent skill
On this page
Related contents
The ScopeDB Agent Skill gives coding and analysis agents such as Claude Code and Codex the workflow to connect to your workspace, write and debug ScopeQL, answer questions from verified query results, and export interactive charts that open offline.
| Capability | What the skill handles | Runtime used when executing |
|---|---|---|
| ScopeQL | Write, explain, translate, and repair queries against ScopeQL syntax, type rules, and functions. | Documentation only; no database connection required. |
| Query | Connect the CLI, inspect tables, run read-only analysis, verify coverage, and maintain project context. | ScopeDB CLI (0.2.x) with an authorized session. |
| Visualization | Map verified query results into ScopeView documents and export standalone interactive HTML charts. | @scopedb/scopeview CLI (Node.js 24+). |
Install the skill
Paste this prompt into an agent with web and terminal access to install the skill and start the guided setup:
Install the ScopeDB skill from https://github.com/scopedb/scopedb-skills and help me get started.You can also install the skill directly from scopedb/scopedb-skills using one of the methods below. Choose one installer per agent and scope so your agent loads a single copy.
With Node.js and npm available, run the Skills CLI from the project where you want to use the skill:
npx skills add scopedb/scopedb-skills --copySelect your agent in the prompt, or pass --agent claude-code or --agent codex. Add --global to install the skill for your user account across projects:
npx skills add scopedb/scopedb-skills --agent codex --global --copyTo update an existing installation later, run npx skills update scopedb --project or npx skills update scopedb --global.
In Claude Code, add the repository as a plugin marketplace and install the scopedb plugin:
/plugin marketplace add scopedb/scopedb-skills
/plugin install scopedb@scopedb-skillsTo update the plugin later, run /plugin marketplace update scopedb-skills followed by /plugin update scopedb@scopedb-skills, then restart your Claude Code session.
Ask Codex to install the skill with its built-in $skill-installer:
Use $skill-installer to install the ScopeDB skill from
https://github.com/scopedb/scopedb-skills/tree/main/skills/scopedbThis installs the skill into $CODEX_HOME/skills/scopedb/ (usually ~/.codex/skills/scopedb/).
Connect and run read-only queries
For live queries, the skill uses the ScopeDB CLI and reuses your active workspace and credentials. If the CLI is not installed or no session is configured yet, your agent guides you through installing scope and authenticating:
- Local terminal agents can sign in through your browser with
scope auth loginand select a workspace withscope workspace use '<id-or-name>'. - Remote or containerized agents can sign in with
scope auth login --use-device-code --no-browseror useSCOPEDB_ENDPOINTandSCOPEDB_API_KEYfrom Connect a client.
Once connected, the skill keeps database access read-only by default. It verifies connectivity with SELECT 1 AS ready, inspects user tables in system.tables and table schemas with DESCRIBE TABLE, and returns answers backed by the executed ScopeQL statement, time window, and result summary. It does not switch your selected workspace or create, alter, or drop database objects unless you explicitly ask it to apply a Catalog change.
Ask questions naturally in your conversation, or invoke $scopedb where your agent supports explicit skill commands:
"Connect to my ScopeDB workspace, inspect the available tables, and suggest a first question to explore.""Using my connected ScopeDB workspace, compare p95 request latency by service over the last 24 hours.""Explain why this ScopeQL query loses the time column after SELECT, and fix it without connecting."
Keep reusable context across sessions
When an analysis depends on domain conventions—such as which table holds canonical orders, how duplicate retries are filtered, or which timestamp defines a reporting window—ask your agent to record confirmed definitions in a project file such as CONTEXT.md.
The skill structures saved context around four sections:
- Scope and sources: Target workspace, qualified table names, and what a single row represents.
- Definitions and data: Confirmed metric rules, event-time columns, reporting timezone, and exclusions such as test accounts or retries.
- Reusable queries: Validated ScopeQL statements for recurring investigations.
- Open questions: Provisional assumptions that still need confirmation from your team.
Your agent reads CONTEXT.md in future sessions so follow-up questions reuse the same definitions without repeating schema discovery. Keep credentials and raw customer records out of context files.
Turn results into interactive charts
When a question is best answered visually—or when you ask to chart a live or saved query result—the skill maps the verified rows and field types into a ScopeView document and renders a self-contained HTML chart with @scopedb/scopeview.
In environments with Node.js 24 or later and npm, the skill validates and renders the chart on demand without modifying your project's package.json:
npm exec --yes --ignore-scripts --package='@scopedb/scopeview@~0.1.1' -- scopeview validate document.json --json
npm exec --yes --ignore-scripts --package='@scopedb/scopeview@~0.1.1' -- scopeview render document.json --output chart.html --theme system --jsonThe exported .html file opens directly in any browser, works offline, and preserves the exact query values, units, and reporting window alongside the chart.