Data Analysis

Data Analysis

Give a host agent Data AI-style intelligent retrieval and analysis capability.

MANDATORY EXECUTION RULE: When this skill is triggered, execute data work only through this skill's bundled CLI commands and their command-specific parameter validation.

Do not bypass the skill by using arbitrary database CLIs, direct ad hoc connections, shell scripts, notebooks, application source code, or unchecked SQL execution. If the CLI cannot perform the requested step, return the missing capability and the next required input instead of inventing results.

The bundled CLI is:

"$SKILL_DIR/venv/bin/python" "$SKILL_DIR/scripts/data_analysis_cli.py"

Use it for data exploration, SQL validation, SQL execution, and answer artifact generation. Pass runtime configuration as explicit CLI arguments using environment-variable placeholders such as --engine-kind "$SQL_ENGINE_KIND" and a selected engine DSN placeholder such as --dsn "$SQL_ENGINE_MYSQL_DSN", --dsn "$SQL_ENGINE_STARROCKS_DSN", or --dsn "$SQL_ENGINE_TRINO_DSN". Do not pass credentials through chat payloads.

Scope & Boundaries

In scope: data requirement clarification, metadata/DDL exploration, read-only SQL validation, read-only SQL execution, result artifact creation, and answer artifact creation.

Out of scope (do NOT handle):

• DDL/DML/DCL, migrations, backfills, ETL deployment, stored procedure

execution, or data repair.

• Credential discovery, password handling, or connection-string construction

from secrets pasted into chat.

• Unrestricted data export or bulk PII extraction.
• BI dashboard editing, frontend work, Flink operations, or cloud resource

management.

Boundary Response

For mutation or data-repair requests:

> "This request is outside the scope of data-analysis. This skill only handles > metadata exploration, read-only SQL validation/execution, and answer artifacts. > It does not modify database schemas, repair data, run ETL, or perform > DDL/DML."

For credential requests:

> "This skill cannot inspect, print, or construct credentials. Configure > SQL_ENGINE_KIND, the matching engine DSN, and optional vector store environment > variables outside the chat payload."

Trigger Conditions

Trigger this skill when the request contains one or more:

1. Data retrieval or analysis terms: 取数, 数据分析, SQL分析, 报表,

明细, 汇总, 指标, 口径, GMV, 订单数, 转化率.

1. Table/metadata exploration terms: 有什么表, 字段, DDL, 表结构,

可用数据, 数据口径.

1. Read-only SQL execution intent: generate/check/execute SELECT or WITH,

run a query, export result file, or explain query output.

Do not trigger for unrelated "analysis" contexts such as code review, frontend layout analysis, Flink job operations, generic cloud infrastructure, or database mutation tasks.

Scope

Supported capabilities:

• Clarify ambiguous data requirements before SQL analysis.
• Explore available business data scopes, fields, metrics, time fields, and

candidate tables without exposing raw table names as the primary user choice.

• Execute one agent-generated read-only SQL statement after the requirement and

relevant schema context are clear.

• Explain result artifacts, assumptions, SQL used, row limits, and caveats.

Out of scope:

• DDL, DML, DCL, migrations, backfills, ETL deployment, stored procedure

execution, or data repair.

• Credential discovery, password handling, or connection-string construction

from secrets pasted into chat.

• Unbounded data export or unrestricted PII disclosure.
• Fabricating query results when execution fails or no engine is selected.

Declared Tool Surface

Use these CLI commands only:

• clarify_requirement: classify the request, identify missing slots, and ask a

focused clarification question; this is an agent-side reasoning step.

• data_exploration: discover relevant table DDL from

the configured vector store, or from SQL introspection when no vector store is configured.

• validate_sql: validate one read-only SQL statement before execution.
• sql_analysis: validate and execute one read-only SQL statement, then write

rows to an artifact file. The command response must not include result rows.

• answer_result: create an answer artifact from a SQL result file.

Command Quick Reference

| User Intent | Command | Type | | --- | --- | --- | | 查可用表/字段/DDL | data_exploration --input | Read | | 校验 SQL | validate_sql --sql --engine-kind "$SQL_ENGINE_KIND" | Read | | 执行只读 SQL | sql_analysis --sql --engine-kind "$SQL_ENGINE_KIND" --dsn "" | Read | | 基于结果文件生成回答 | answer_result --input | Read |

For SQL execution, choose the DSN placeholder by SQL_ENGINE_KIND: mysql uses SQL_ENGINE_MYSQL_DSN, starrocks uses SQL_ENGINE_STARROCKS_DSN, and trino uses SQL_ENGINE_TRINO_DSN. For metadata exploration, choose Chroma or StarRocks vector arguments by VECTOR_STORE_PROVIDER.

sql_analysis is the only command that requires --sql or input payload field sql. Other commands should rely on their own CLI validation and should not inherit SQL-specific checks.

Operating Flow

1. Classify intent as detail, summary, direct_answer, data_exploration,

sql_analysis, answer_result, or boundary.

1. If the request is ambiguous, follow

references/requirement-clarification.md.

1. If the business scope is unclear, run lightweight data_exploration first.

Use business language in the response; do not ask the user to choose raw table names.

1. Use environment-variable placeholders in the Bash command for runtime

configuration. Never print their resolved values.

1. For SQL work, follow references/sql-safety.md. Only one SELECT or WITH

statement is allowed. Validate the generated SQL with:

``bash "$SKILL_DIR/venv/bin/python" "$SKILL_DIR/scripts/data_analysis_cli.py" validate_sql --sql "" --engine-kind "$SQL_ENGINE_KIND" ``

1. Execute the query through sql_analysis only after required slots and

relevant schema context are known. Use --input or stdin and pass --engine-kind "$SQL_ENGINE_KIND" plus the matching engine DSN: mysql -> --dsn "$SQL_ENGINE_MYSQL_DSN", starrocks -> --dsn "$SQL_ENGINE_STARROCKS_DSN", trino -> --dsn "$SQL_ENGINE_TRINO_DSN".

1. Return result paths, row counts, assumptions, defaults, and warnings. Do not

paste result rows into the chat unless the user explicitly asks for a small preview.

Required Slots

For detail requests:

• business_object
• time_field
• time_range
• output_fields

Default only when the user allows it:

• limit_sort: sort by the selected time field descending and limit to 100

rows.

For summary requests:

• business_object
• time_field
• time_range
• metrics
• dimensions

If only default slots are missing, continue and state the defaults in the final answer. Do not silently choose a time field.

Safety Rules

• Treat all SQL as unsafe until it passes validation.
• Allow only a single read-only SELECT or WITH statement.
• Reject INSERT, UPDATE, DELETE, MERGE, DROP, ALTER, CREATE,

TRUNCATE, CALL, EXEC, GRANT, REVOKE, USE, SET, multi-statements, shell escapes, and comments that hide extra statements.

• Add or preserve an explicit row limit for detail queries unless the user has

permission for export and the runtime enforces an export boundary.

• Mask or avoid unnecessary PII in previews and natural-language summaries.
• Never reveal credentials, connection strings, API keys, or raw secret values.

Resources

Load After Trigger

• references/command-map.md — Intent-to-command routing and first-call rules.
• references/agent-operating-protocol.md — Execution flow, parameter strategy,

and response rules.

Load On Demand

• references/requirement-clarification.md — Read when the user request lacks

business object, time field/range, metrics, dimensions, or output fields.

• references/sql-safety.md — Read before validating or executing SQL.
• references/command-catalog.md — Read for command syntax, payload examples,

environment variables, and error codes.

• references/error-handling.md — Read when any CLI command returns ok: false

or exits non-zero.

• references/table-catalog.md — Read when the user asks about known business

table areas from the Data AI project.

Assets

• scripts/data_analysis_cli.py — Main CLI entry.
• requirement.txt — Python dependencies for the skill-local venv.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TKilome
• Source: TKilome/skillbound-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.