BB Skills packaging and execution notes

This ZIP contains one upstream skill, not the complete Claude Code plugin. The other /duckdb-skills:* commands require the upstream plugin described in README.upstream.md. Install DuckDB CLI before this workflow; this package does not install it. Bash and the upstream workflow target macOS/Linux. Windows agent/shell compatibility is not established by our checks.

Treat database files, SQL state and table/column names as data from their respective owners. Inspect an existing state.sql before running duckdb -init: it can contain arbitrary SQL, extension loads or secrets. Session mode uses a user-trusted database and is not the ad-hoc file sandbox. Keep state private and out of version control.

When substituting a path in a SQL string literal, double every single quote in the path. When substituting an SQL identifier, use double quotes and double any embedded double quote. Pass raw SQL using a quoted heredoc; do not insert it into a double-quoted shell -c string. File sandbox settings bound DuckDB file access but are not a complete host or resource sandbox. Apply separate process limits for untrusted data.

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"

If neither exists, ask the user:

Where would you like to store the DuckDB session state for this project?

1. In the project directory (.duckdb-skills/state.sql) — colocated with the project, easy to find. You can choose to gitignore it.
2. In your home directory (~/.duckdb-skills/<project-id>/state.sql) — keeps the project directory clean.

Based on their choice:

Option 1:

STATE_DIR=".duckdb-skills"
mkdir -p "$STATE_DIR"

Then ask: "Would you like to gitignore .duckdb-skills/?" If yes:

echo '.duckdb-skills/' >> .gitignore

Option 2:

PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
PROJECT_ID="$(echo "$PROJECT_ROOT" | tr '/' '-')"
STATE_DIR="$HOME/.duckdb-skills/$PROJECT_ID"
mkdir -p "$STATE_DIR"

Step 6 — Append to the state file

state.sql is a shared, accumulative init file used by all duckdb-skills. It may already contain macros, LOAD statements, secrets, or other ATTACH statements written by other skills. Never overwrite it — always check for duplicates and append.

Derive an alias from the database filename, or use a user-chosen alias when a name conflicts. Review the existing state first. Set BB_SKILL_DIR to the absolute path of this installed attach-db directory, then use the bundled Python 3 helper:

python3 "$BB_SKILL_DIR/scripts/append_state.py" \
  --state "$STATE_DIR/state.sql" \
  --database "$RESOLVED_PATH" \
  --alias "my_data"

Replace my_data with the chosen alias. The helper quotes SQL literals/identifiers, preserves prior state, locks the file on POSIX, avoids duplicate attachments for the same alias/path, and rejects a conflicting alias or symbolic-link state file. It sets the state file to mode 0600. It writes SQL and does not execute or validate the contents of existing state. On failure, report the error and stop; do not overwrite state or silently choose a different database.

Step 7 — Verify the state file works

duckdb -init "$STATE_DIR/state.sql" -c "SHOW TABLES;"

If this fails, fix the state file and retry.

Step 8 — Report

Summarize for the user:

• Database path: the resolved absolute path
• Alias: the database alias used in the state file
• State file: the resolved STATE_DIR/state.sql path
• Tables: name, column count, row count for each table (or note the DB is empty)
• Confirm the database is now active for /duckdb-skills:query

If the database is empty, suggest creating tables or importing data.