SQL Analysis
Businesssql-analysisSQL Analysis is an Agent Skill for business published in the agentscope-ai/agentscope-java repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at 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 and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/sql-analysis, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
SQL Analysis Skill
Repeatable SOP for turning a business question into a verifiable SQL answer.
Steps
-
Restate the question as a metric. In one sentence, write: " by over , filtered by ". If any of those four (metric / grouping / window / filter) is missing or ambiguous, ask one clarifying question and stop. Do not guess.
-
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-explorersub-agent with the metric definition as the prompt — its job is to identify the canonical source.
- Look in
-
Draft the query. Write the SQL in a fenced
sqlblock. Conventions:- Always include the time window in a
WHEREclause — never query the full history "just in case". - Always
SELECTan explicit column list — neverSELECT *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).
- Always include the time window in a
-
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
NULLs 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.
-
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> ## Query ```sql <the exact query you ran>Sources & validation
- Table(s):
schema.table_name(row count, freshness if known) - Validation:
- Caveats: <known data quality issues, missing dates, etc.>
- Table(s):
Anti-patterns
- ❌ Reporting a number without the query that produced it.
- ❌ Using
LIMIT Nto "make the output fit" without explaining what got cut. - ❌ Reading a single row and reporting it as a trend.
- ❌ Inventing a table or column name. If unsure, delegate to
data-explorer.
When to delegate
- The user's question requires probing several candidate tables / sources
before any query can be written → spawn
data-explorer. - The user wants a polished written deliverable summarising several analyses
(e.g. "weekly health report") → spawn
report-writerafter you have the underlying numbers ready.