attach-db

You are helping the user attach a DuckDB database file for interactive querying.

Database path given: $0

Follow these steps in order, stopping and reporting clearly if any step fails.

State file convention: see the "Resolve state directory" section below. All skills share a single state.sql file per project. Once resolved, any skill can use it with duckdb -init "$STATE_DIR/state.sql" -c "<QUERY>".

Step 1 — Resolve the database path

If $0 is a relative path, resolve it against $PWD to get an absolute path (RESOLVED_PATH).

RESOLVED_PATH="$(cd "$(dirname "$0")" 2>/dev/null && pwd)/$(basename "$0")"

Check the file exists:

test -f "$RESOLVED_PATH"

• File exists -> continue to Step 2.
• File not found -> ask the user if they want to create a new empty database (DuckDB creates the file on first write). If yes, continue. If no, stop.

Step 2 — Check DuckDB is installed

command -v duckdb

If not found, delegate to /duckdb-skills:install-duckdb and then continue.

Step 3 — Validate the database

duckdb "$RESOLVED_PATH" -c "PRAGMA version;"

• Success -> continue.
• Failure -> report the error clearly (e.g. corrupt file, not a DuckDB database) and stop.

Step 4 — Explore the schema

First, list all tables:

duckdb "$RESOLVED_PATH" -csv -c "
SELECT table_name, estimated_size
FROM duckdb_tables()
ORDER BY table_name;
"

If the database has no tables, note that it is empty and skip to Step 5.

For each table discovered (up to 20), run:

duckdb "$RESOLVED_PATH" -csv -c "
DESCRIBE <table_name>;
SELECT count() AS row_count FROM <table_name>;
"

Collect the column definitions and row counts for the summary.

Step 5 — Resolve the state directory

Check if a state file already exists in either location:

# Option 1: in the project directory
test -f .duckdb-skills/state.sql && STATE_DIR=".duckdb-skills"

# Option 2: in the home directory, scoped by project root path
PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
PROJECT_ID="$(echo "$PROJECT_ROOT" | tr '/' '-')"
test -f "$HOME/.duckdb-skills/$PROJECT_ID/state.sql" && STATE_DIR="$HOME/.duckdb-skills/$PROJECT_ID"