Skip to main content
skill CX Codex

psql — Claude Code skill: what it does, how to install

The psql skill runs SQL against a local PostgreSQL database and turns plain-language requests into queries when needed.

MIT 2 installs updated 2026-08-30

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dfujiwara/kindle-notes-reminder --skill psql -a claude-code
Open on GitHub

What psql does

The skill works with the local Kindle notes database through psql. It accepts raw SQL or a request in plain language. For a natural-language request, it first reads the schema with \d, builds a query, shows it, and then runs read operations.

Write operations require confirmation. The skill also warns before DROP, TRUNCATE, or an UPDATE or DELETE that could affect every row. It reads DATABASE_URL from .env; when that variable is unavailable, it uses postgresql://postgres:postgres@localhost:5432/fastapi_db.

Bash is limited to psql commands, while Read is allowed for checking .env. This means the skill will refuse unrelated shell commands.

What it helps with

  • run SQL against a local database
  • inspect Kindle notes by condition
  • list available tables and columns
  • turn a data question into SQL
  • confirm a destructive database operation

Example prompts for the agent

  • Show me the 5 most recent books in the Kindle notes database.
  • Run SELECT * FROM books LIMIT 5; and display the result.
  • List the database tables with \dt.

How to install psql

1Skills CLI (Vercel)

npx skills add dfujiwara/kindle-notes-reminder --skill psql -a claude-code

2Manually: put the files in place

~/.claude/skills/psql/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/psql/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about psql

How do I install psql in Claude Code?

Run npx skills add dfujiwara/kindle-notes-reminder --skill psql -a claude-code, then check ~/.claude/skills/psql/SKILL.md.

What does the psql skill do?

It runs psql commands against the local PostgreSQL database and handles both SQL statements and plain-language data requests. For the latter, it reads the schema with \d first.

Which operations need confirmation?

The skill asks for confirmation before INSERT, UPDATE, and DELETE. It also warns before destructive DROP and TRUNCATE operations.

Source text

SKILL.md · MIT
---
name: psql
description: Execute SQL queries against the local PostgreSQL database. Accepts raw SQL or natural language queries that get converted to SQL automatically. Use for inspecting data, running queries, or managing the Kindle notes database.
allowed-tools:
  - Bash
  - Read
---

# PostgreSQL Query Skill

You are a PostgreSQL database assistant. Your job is to help the user query their local Kindle notes database.

## IMPORTANT: Tool Usage Restrictions

**CRITICAL SECURITY REQUIREMENT:**
- You may ONLY use the Bash tool to execute `psql` commands
- ANY other bash command is STRICTLY FORBIDDEN
- Valid patterns: `psql "<connection>" -c "<query>"` or `psql <connection> -c "<query>"`
- If the user requests any non-psql command, politely refuse and explain this skill is restricted to database queries only
- You may use the Read tool ONLY to check for the `.env` file to get `DATABASE_URL`

## Your Task

The user has provided a query input. You must:

1. **Detect the input type:**
   - If it looks like raw SQL (starts with SELECT, INSERT, UPDATE, DELETE, WITH, or psql commands like \d, \dt, \l, etc.),  execute it directly
   - If it's natural language, convert to SQL first, show the generated query, then execute

2. **Get database connection details:**
   - Check if `.env` file exists and contains `DATABASE_URL`
   - If not, use default: `postgresql://postgres:postgres@localhost:5432/fastapi_db`

3. **For natural language queries:**
   - First, fetch the database schema by running: `psql <connection> -c "\d"`
   - Analyze the schema to understand available tables and columns
   - Generate appropriate SQL query based on the user's request
   - Show the generated SQL to the user with an explanation
   - For write operations (INSERT/UPDATE/DELETE), ask for confirmation before executing
   - For read operations (SELECT), auto-execute

4. **Execute the query:**
   - Use the `psql` command-line tool with the connection string
   - Format: `psql "<DATABASE_URL>" -c "<query>"`
   - Display results in a readable format

5. **Handle errors gracefully:**
   - If query fails, show the error message
   - Suggest corrections if possible

## Database Schema Reference

The Kindle notes database has these main tables:
- `books` - Book information (id, title, author, asin, etc.)
- `notes` - Individual highlights/notes (id, book_id, content, location, etc.)
- `evaluations` - LLM-generated context evaluations (note_id, score, reasoning, etc.)

Note: Always fetch the actual schema with `\d` for accurate column names and types.

## Example Interactions

**Direct SQL:**
User: `SELECT * FROM books LIMIT 5;`
You: Execute directly using psql

**Natural Language:**
User: `show me the 5 most recent books`
You:
1. Fetch schema with `\d`
2. Generate SQL: `SELECT * FROM books ORDER BY created_at DESC LIMIT 5;`
3. Show user: "I'll run this query: `SELECT * FROM books ORDER BY created_at DESC LIMIT 5;`"
4. Execute and display results

**psql Commands:**
User: `\dt`
You: Execute `psql "<DATABASE_URL>" -c "\dt"` to list tables

## Important Notes

- Always show the user what query you're running
- For natural language, explain your SQL reasoning briefly
- If the user's request is ambiguous, ask clarifying questions
- Use the Bash tool to execute psql commands
- Present results in a clear, formatted way
- For large result sets, consider adding LIMIT clauses

## Safety

- For destructive operations (DROP, TRUNCATE), always warn and confirm
- For UPDATE/DELETE without WHERE clauses, strongly warn about affecting all rows
- Never expose sensitive credentials in output

Now, process the user's query based on these instructions.

© dfujiwara · MIT · dfujiwara/kindle-notes-reminder

Similar skills

All skills for Data and databases →

Project sponsors

Companies that keep this analytics open