# SQL Analysis

Answer a quantitative business question by writing a SQL query against the data...

- Repository: https://github.com/agentscope-ai/agentscope-java (6205 stars)
- Category: Data and ML
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add agentscope-ai/agentscope-java --skill sql-analysis -g -a claude-code -y`
Codex: `npx skills add agentscope-ai/agentscope-java --skill sql-analysis -g -a codex -y`
Cursor: `npx skills add agentscope-ai/agentscope-java --skill sql-analysis -g -a cursor -y`
Gemini CLI: `npx skills add agentscope-ai/agentscope-java --skill sql-analysis -g -a gemini-cli -y`

## Description

Answer a quantitative business question by writing a SQL query against the data warehouse, validating it, and presenting the result. Use when the user asks "how many...", "what's the trend of...", "compare X vs Y over...", "what's our top N...", or anything that resolves to a query against tabular data. Produces a small result table plus the underlying query.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# SQL Analysis Skill

Repeatable SOP for turning a business question into a verifiable SQL answer.

## Steps

1. **Restate the question as a metric.** In one sentence, write:
   *"<metric> by <grouping> over <time window>, filtered by <filter>"*.
   If any of those four (metric / grouping / window / filter) is missing or
   ambiguous, ask **one** clarifying question and stop. Do not guess.

2. **Locate the source.** Decide where the data lives:
   - Look in `knowledge/` first for any schema notes, data-dictionary entries,
     or prior query examples uploaded by the user.
   - If the right table is not obvious, **delegate to the `data-explorer`
     sub-agent** with the metric definition as the prompt, its job is to
     identify the canonical source.

3. **Draft the query.** Write the SQL in a fenced ```sql``` block. Conventions:
   - Always include the time window in a `WHERE` clause, never query the
     full history "just in case".
   - Always `SELECT` an explicit column list, never `SELECT *` in an answer.
   - Use CTEs (`WITH x AS (...)`) over nested subqueries for anything beyond
     two levels of nesting.
   - Comment any non-obvious filter (`-- excludes internal test accounts`).

4. **Validate before reporting.** Run the query and check:
   - Row count is in the ballpark you expected (1 row, 10 rows, ~30 daily
     buckets, etc.). A surprising row count is almost always a bug, investigate.
   - No `NULL`s in the grouping column unless that is the intended cohort.
   - At least one numeric sanity check: a known total, a known reference value,
     or a min/max range that matches reality.
   - If anything looks off, **do not report the number**, fix the query first.

5. **Write the report.** Use this exact structure:

   ```
   ## Answer
   <one-sentence direct answer with the headline number(s)>

   ## Result
   <small markdown table, at most ~15 rows; for longer results, summarise
   and offer to render a chart or attach the full CSV>

The rest: https://github.com/agentscope-ai/agentscope-java/blob/HEAD/agentscope-examples/agents/agentscope-dataagent/src/main/resources/shared/agents/data-agent/skills/sql-analysis/SKILL.md