How to use the Database Optimizer agent skill

What the Database Optimizer skill makes the agent do

Once the skill is loaded, the agent follows a fixed workflow for database slowness: capture a baseline, find the bottlenecks, design a fix, apply it one change at a time and validate the result. It is designed for performance work such as reading execution plans, spotting missing indexes or stale statistics, rewriting queries, tuning configuration, planning partitioning and resolving lock contention.

The skill's output is meant to include a baseline with query time, cost and buffer hit ratio, the bottlenecks with EXPLAIN evidence, the SQL or configuration changes, validation queries and monitoring recommendations.

• Asks for or captures baseline measurements before any change
• Reads EXPLAIN ANALYZE output and points to specific patterns such as Seq Scan, Nested Loop and external merge sorts
• Proposes index designs, query rewrites and configuration changes with the SQL to apply them
• Provides validation queries and a monitoring checklist

Install the skill from the ZIP download

Download the ZIP for the database-optimizer skill from the page where you found this guide. Then choose one of two options depending on where you want the skill to live.

For a personal install available across your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project. Either way the skill's folder should contain SKILL.md and the references folder.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

You do not need a special command. The skill's description tells the agent when to use it, so ordinary requests about slow queries, execution plans or database performance should trigger it. Describe the symptom and give the agent access to what it needs, such as your connection or pasted EXPLAIN output.

Good requests name the database, the query or endpoint, and what you have already measured. The skill also lists trigger phrases such as slow query, query performance, index optimization and EXPLAIN ANALYZE, so using those words helps.

• "This orders query takes 4 seconds in PostgreSQL. Here is the EXPLAIN ANALYZE output. Find the bottleneck."
• "Our MySQL endpoint for customer search is slow. Check the performance_schema for the worst statements and propose indexes."
• "Review this index plan for the orders table and tell me how to add it without locking production."
• "Suggest PostgreSQL configuration changes for a server with lock contention during peak hours."

Prerequisites and what the agent needs

The skill itself has no software to install. Its examples depend on the database features they use. The top-slow-query example for PostgreSQL requires the pg_stat_statements extension. The MySQL examples require performance_schema to be enabled.

The agent needs database access with rights to run EXPLAIN ANALYZE and read statistics views. If you cannot give it a connection, paste the relevant output yourself.

• PostgreSQL with pg_stat_statements for the top-slow-query example
• MySQL with performance_schema enabled for the MySQL examples
• Rights to run EXPLAIN ANALYZE and read statistics views, or pasted output
• The skill runs no scripts and uses no network access, according to its listing

Safety: test first and review every change

The skill says changes should be tested in non-production first, and that you should revert immediately if write performance degrades or replication lag increases. Index and configuration changes can slow writes and affect replication, so treat each suggestion as a proposal.

The skill gives SQL and commands but does not restrict what the agent executes. Do not let the agent run statements against a live database without reviewing them yourself. Where the skill asks for CREATE INDEX CONCURRENTLY on PostgreSQL, that is intended to avoid table locks, but you should still confirm it on a staging copy first.

• Use a staging copy of the database before applying anything
• Read each SQL statement before running it
• Apply one change at a time and measure before and after
• Watch write performance and replication lag after each change

Tips for better results

Give a baseline up front. The skill is built around measured before-and-after comparisons, so a query time and an EXPLAIN ANALYZE plan will get you much more useful advice than a general description.

Ask for one change at a time. The skill says multiple simultaneous changes make the impact impossible to attribute. Also ask the agent to check for redundant indexes, since the skill warns against them.

• Include the full EXPLAIN (ANALYZE, BUFFERS) output where possible
• Ask for validation queries so you can confirm the improvement
• Ask for a monitoring checklist once the fix is in place