How to use the Fix Slow Database Queries agent skill

What is an agent skill?

An agent skill is a folder containing a SKILL.md file and optional reference files and scripts. When the skill is installed, the agent reads its description and loads the full instructions when a request matches. The skill tells the agent how to work, in what order, and what counts as finished.

This skill's SKILL.md says it applies to costly queries, repeated database work, or slow requests with a suspected database cause.

What does the skill make the agent do?

The skill sets a structured, evidence-first workflow. The agent starts from production evidence such as query statistics and Neon database metadata, traces each slow query back to the code that generates it, reproduces the slowness on a local PostgreSQL with synthetic data, and only then makes a change.

Each change must be shown to be faster and to return identical results. The skill also expects regression tests and passing checks before a pull request is considered done. A list of suspicious SQL is treated as an intermediate result, not a finished job.

• Identify the target URL, environment, deployed revision and owning repository
• Rank the top two or three query families by cost and frequency
• Reproduce the baseline locally with EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) output saved
• Compare baseline and treatment for both performance and correct results
• Verify the blast radius with regression tests and the repository's pre-PR checks

How do you install the skill?

Download the ZIP for fix-slow-queries from this page. Unzip it into one of two locations. For a personal install, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills. The package contains agents/openai.yaml, references/cloud-discovery.md, references/local-proof.md and SKILL.md.

• Personal: unzip into ~/.claude/skills/
• Project: unzip into the project's .claude/skills/
• Claude apps: Settings → Capabilities → Skills, then upload

How do you trigger the skill with a natural request?

You do not need a special command. Describe the problem in plain language and mention the slow thing you observed. The skill's description matches requests about costly queries, repeated database work, or slow requests with a suspected database cause.

If you only want an answer and not a fix, say so. The skill says to respect a narrower request for diagnosis only.

• "This workspace task endpoint is slow. Find the database queries behind it and fix them."
• "Investigate the top costly queries in our Paperclip Neon project and propose a measured fix with a PR."
• "Only diagnose the slow history request. Do not change code yet."

What does it need before you run it?

The skill needs a local Git checkout of the Paperclip repository, local PostgreSQL for disposable benchmark databases, and ripgrep (rg) for code search. Hosted diagnosis also requires access to the private paperclip-cloud control plane and the Neon project. The source does not say how those credentials are supplied, so check with your team.

Use it on Paperclip itself. Its paths, rules and tooling are specific to that repository and its private control plane, so it will mislead on other projects.

• Git and a local checkout of the Paperclip repository
• Local PostgreSQL for disposable benchmark databases
• ripgrep (rg)
• Access to paperclip-cloud and the Neon project, for hosted diagnosis only

What are the safety notes for scripts and network use?

This skill runs scripts and uses the network. The benchmark harnesses live in scripts/benchmark-*.ts and packages/db/src. The skill says to inspect a harness before running it, and to use disposable synthetic fixtures.

The skill can involve migrations, schema changes and access to hosted infrastructure. Do not let an agent change a production database directly. Migrations that exceed the roughly one-to-two-minute budget must be flagged for human review, and the skill forbids adding startup scripts, boot-time DDL or recurring backfills to avoid a migration constraint.

• Inspect scripts/benchmark-*.ts before running them
• Run benchmarks only against disposable local PostgreSQL
• Keep human review on any migration, schema change or production-touching step
• Do not treat an interrupted test suite as a pass

What tips help you get good results?

Give the agent the reported URL, environment and a representative slow request, since the skill starts there. Expect a long run: the workflow expects a full fix, branch and pull request, and it will record deferred candidates rather than rewrite everything.

Keep the checkout that runs a live server separate from branch switching and benchmark setup. The skill recommends a dedicated branch or worktree.

• Provide UTC observation times and a specific slow endpoint
• Ask for a bounded batch, such as the top two or three query families
• Read the saved baseline and EXPLAIN output before accepting a fix
• Check that the final commit of the PR passes its checks