Guide · Agent skill
How to use the MySQL Reporter agent skill for SQL reports
Updated · written with AI from the project's own documentation and checked against our catalogue data
MySQL Reporter is an agent skill: a packaged set of instructions and small Python scripts that an AI agent can load and use. Once it is installed, you can ask the agent in plain language for a sales, user or business metric report from a MySQL database, and it will query the data and return tables, key figures and conclusions. This guide is for analysts and teams who have not used agent skills before. By the end you will know what the skill does, how to install it, how to configure its database settings, and how to make requests that get useful results.
MySQL Reporterxerrors/Yuxi · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it. Keep the folder name mysql-reporter so the paths in the skill still match.
- 2Place it where your agent can find it. Put the folder in ~/.claude/skills/ for personal use, or in a project's .claude/skills/ folder. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills instead.
- 3Set the MySQL environment variables. In your personal settings, add MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD and MYSQL_DATABASE under sandbox environment variables. Add MYSQL_PORT and MYSQL_DATABASE_DESCRIPTION if you need them.
- 4Start a new session. Changes to sandbox variables apply only to newly created sandboxes, so begin a fresh task or conversation after saving.
- 5Ask for a report. Describe the question in plain language, for example a monthly sales total for last quarter. The agent lists tables, checks structures and runs read-only queries.
- 6Review the results. Check the figures and conclusions in the Markdown tables against what you expect, and ask follow-up questions to narrow or extend the analysis.
What the MySQL Reporter skill makes the agent do
The skill is for turning a database question into a report. Its description covers tasks such as counting sales data, analysing user behaviour, producing business reports and checking business metrics.
When the skill is active, the agent works through a fixed sequence: it clarifies what the report should answer, lists the available tables, inspects table structures where needed, writes a read-only SELECT-style query, runs it, and presents the results as a Markdown table with the key metrics, changes and conclusions.
- Lists tables in the configured MySQL database
- Shows the structure of a named table
- Runs read-only queries and returns the results for a report
- Writes the report with tables, key figures and conclusions
Install the MySQL Reporter skill
Download the skill ZIP from this page and unzip it. You can install it in one of two ways.
For Claude Code, unzip the folder into your personal skills directory ~/.claude/skills/, or into a project's .claude/skills/ directory if you want the skill available only in that project. For the Claude apps, upload the ZIP under Settings, then Capabilities, then Skills.
- Personal use with Claude Code: place the unzipped folder in ~/.claude/skills/
- Single project: place the unzipped folder in the project's .claude/skills/ directory
- Claude apps: upload the ZIP under Settings → Capabilities → Skills
Configure the database connection
The scripts read connection details only from environment variables in the agent's sandbox. They do not read a backend .env file or Docker Compose variables. Four variables are required: MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD and MYSQL_DATABASE.
Three are optional. MYSQL_PORT defaults to 3306. MYSQL_DATABASE_DESCRIPTION is a plain-language description of the business and its tables, which helps the agent interpret table and metric names. The database must be reachable from the agent sandbox, and the scripts need Python with uv, since they run via uv run.
- Required: MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE
- Optional: MYSQL_PORT (default 3306), MYSQL_DATABASE_DESCRIPTION
- Add them under the sandbox environment variables in your personal settings
- Changes apply to newly created sandboxes, so start a new task or session after saving
How the agent runs the scripts
The skill tells the agent to run its three scripts from the terminal. The example in the skill changes into the skill folder first, using the path /home/user/skills/mysql-reporter, so adjust that path to where you put the folder on your machine.
The agent uses list_tables.py to see what is available, describe_table.py when it needs column details, and query.py to execute a query with a time limit of 60 in the example.
- scripts/list_tables.py lists tables
- scripts/describe_table.py --table takes a table name and shows its structure
- scripts/query.py --sql takes a SQL statement and --timeout sets the limit
cd /home/user/skills/mysql-reporter
uv run scripts/list_tables.py
uv run scripts/describe_table.py --table 表名
uv run scripts/query.py --sql "SELECT ..." --timeout 60Ask for a report in natural language
You do not need to name the skill or write SQL. Describe the report you want, including the time period, the metric and any grouping. The skill's description is written so that requests about querying a MySQL database and presenting results as a report will trigger it.
If the agent reports missing configuration, it is designed to tell you which variable names are missing and stop there, rather than guessing a connection or inventing figures. It will not print your password.
- Name the business question, time period and metric
- Say how you want results grouped, such as by month or by region
- Ask for conclusions if you want more than a table
Safety notes: scripts and network access
This skill runs scripts and uses the network. The scripts connect to your MySQL server, and the skill's permitted tools include a network search tool that the agent may use to add background information. The scripts check that queries are read-only and that table names are safe, but you should still treat the database account as the real boundary.
The skill instructs the agent not to output sensitive environment variable values, including the password, and not to include raw SQL in the report. Use a read-only account or a read-only reporting replica, and review what that account can read before connecting it to a database with personal data.
- Use a read-only database account, ideally on a reporting replica
- Do not point the skill at production write access
- Check what tables the account can read before use, because the agent reads whatever it can access
- Expect the agent to hide the password and raw SQL from its reports
What people use it for
- Summarising monthly sales totals and changes from a reporting database
- Analysing user behaviour metrics such as activity or sign-ups by period
- Producing a business metrics overview with tables, key figures and conclusions
- Checking which tables exist and what columns they hold before building a report
Frequently asked questions
What is the MySQL Reporter agent skill?
It is an agent skill that lets an AI agent query a MySQL database through small Python scripts and present the results as a report. It is designed for read-only SELECT-style queries and is described as generating reports for sales, user behaviour and business metrics.
Do I need to know SQL to use it?
No. You describe the report in plain language and the agent writes and runs the read-only SQL. You can still review the figures it returns, and the skill tells the agent not to include raw SQL in the report itself.
What do I need to run the MySQL Reporter skill?
You need Python with uv, since the scripts run via uv run, and a MySQL database reachable from the agent sandbox. You also need the MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD and MYSQL_DATABASE environment variables, with MYSQL_PORT and MYSQL_DATABASE_DESCRIPTION optional.
Is the MySQL Reporter skill free?
The skill is listed under the MIT licence. Check the licence file in the source repository for the full terms before using or redistributing it.
Why does the agent say MySQL configuration is missing?
The scripts only read environment variables from the agent sandbox, not from a backend .env file or Docker Compose. Add the missing MYSQL_ variables in your sandbox environment settings, then start a new session, because changes apply to newly created sandboxes.
Can the skill change or delete data?
It is designed for read-only queries and should not be pointed at production write access. The scripts check that queries are read-only, but you should also use a read-only database account for real protection.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
MySQL Reporter suits analysts and teams who want to ask plain-language questions of a MySQL database and get structured reports, especially if they have a read-only reporting replica. It is a poor fit if you need an agent to change data, or if you plan to connect it to sensitive data without first reviewing what the database account can read.
Download the skill