dev10x-db:sql-handoff
/dev10x-db:sql-handoff
Use when a write (UPDATE, INSERT, DELETE, DDL) must reach a database the agent can only read through dev10x-db:db-psql — so the supervisor gets one paste-safe statement aimed at the right database, and the agent proves the effect before building on it. TRIGGER when: the agent needs the user to run non-SELECT SQL by hand, or the db-psql hook just blocked a write. DO NOT TRIGGER when: the SQL is a SELECT (run it via dev10x-db:db-psql), or the change belongs in a migration file in the codebase.
- Author
- dev10x-guru ↗
- Repository
- dev10x-claude ↗
- Licence
- MIT
- Last repository change
- 08.11.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 08.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when a write (UPDATE, INSERT, DELETE, DDL) must reach a database the agent can only read through dev10x-db:db-psql — so the supervisor gets one paste-safe statement aimed at the right database, and the agent proves the effect before building on it. TRIGGER when: the agent needs the user to run non-SELECT SQL by hand, or the db-psql hook just blocked a write. DO NOT TRIGGER when: the SQL is a SELECT (run it via dev10x-db:db-psql), or the change belongs in a migration file in the codebase.
Original author description
Use when a write (UPDATE, INSERT, DELETE, DDL) must reach a database the agent can only read through dev10x-db:db-psql — so the supervisor gets one paste-safe statement aimed at the right database, and the agent proves the effect before building on it. TRIGGER when: the agent needs the user to run non-SELECT SQL by hand, or the db-psql hook just blocked a write. DO NOT TRIGGER when: the SQL is a SELECT (run it via dev10x-db:db-psql), or the change belongs in a migration file in the codebase.
How it works
- Orchestration
- Overview
- The Rules
- Workflow
- Gotchas
- Examples
- Integration
SKILL.md preview
---
name: dev10x-db:sql-handoff
description: >
Use when a write (UPDATE, INSERT, DELETE, DDL) must reach a database
the agent can only read through dev10x-db:db-psql — so the supervisor
gets one paste-safe statement aimed at the right database, and the
agent proves the effect before building on it.
TRIGGER when: the agent needs the user to run non-SELECT SQL by hand,
or the db-psql hook just blocked a write.
DO NOT TRIGGER when: the SQL is a SELECT (run it via dev10x-db:db-psql),
or the change belongs in a migration file in the codebase.
user-invocable: true
invocation-name: dev10x-db:sql-handoff
allowed-tools:
- AskUserQuestion
- Bash(${CLAUDE_PLUGIN_ROOT}/skills/db-psql/scripts/db.sh:*)
---
# dev10x-db:sql-handoff
**Announce:** "Using dev10x-db:sql-handoff to hand the write to you and
verify it afterwards."
## Orchestration
This skill follows `references/task-orchestration.md` patterns.
**REQUIRED: Create a task at invocation.** Execute at startup:
1. `TaskCreate(subject="Hand off SQL write to supervisor", activeForm="Handing off SQL")`
Mark completed only after Step 5 verifies the write:
`TaskUpdate(taskId, status="completed")`
## Overview
The agent may run SELECTs through `dev10x-db:db-psql`; every write goes
through the supervisor's own psql session. The handoff is where a
write goes wrong: the wrong database, a stale WHERE clause, a
statement mangled in the copy-paste, or an agent that assumes "done"
means "worked". The five rules below close each of those gaps. One
handoff carries exactly one statement.
## The Rules
1. **Never put SQL inside an `AskUserQuestion` prompt.** The widget
renders with box-drawing characters, and copying out of it
carries them into psql (see Gotchas). Print the SQL first, in
plain chat text, as a fenced `sql` block whose **first line** is
the target header:
```sql
-- Run against: <alias> (<label>)
```
Then ask with `AskUserQuestion` — a question that only *refers*
to the block above, never one that contains it.
2. **Verify with a SELECT after the user says it ran.** Run a
read-back through `dev10x-db:db-psql` before continuing. Never trust
the paste, a pasted psql output, or "done" on its own.
3. **One statement per handoff.** State the exact WHERE clause and
the expected row count (`-- Expect: UPDATE 1`) inside the block.
A second write waits for the first one's verification.
4. **Confirm the target first when the row is ambiguous.** If more
than one row could match, or the agent picked the row from
inference rather than a primary key, run (or hand over) a SELECT
with the same WHERE clause first, and only write once it returns
exactly the expected rows.
5. **Never bypass the read-only hook or wrap writes in scripts.** No
`psql -c`, no `-f /tmp/fix.sql` through `db.sh`, no Python or
shell wrapper that opens a connection, no `BEGIN; ... COMMIT;`
smuggled into a SELECT. The hook block is the signal to hand off,
not an obstacle to route around.
## Workflow
### Step 1: Pin the target
Resolve the alias and label from `databases.yaml`
(`db.sh --list`). Build the WHERE clause from a primary key
whenever one is known. If the target is ambiguous, apply Rule 4
before Step 2.
### Step 2: Print the statement
In plain chat text, not inside a tool call:
````markdown
```sql
-- Run against: bs (backend-staging)
-- Expect: UPDATE 1
UPDATE shop SET is_active = false WHERE id = 4182;
```
````
The block holds the header, the expected count, and one statement
— nothing else for the user to trim.
### Step 3: Ask about the block
**REQUIRED: Call `AskUserQuestion`** (do NOT use plain text). The
question names the statement and the alias but holds no SQL, e.g.
"Did you run the UPDATE above on bs?". Options:
- Done, ran it (Recommended) — psql reported the expected count
- Use a different row — the target is wrong; re-pin it
- Didn't run it — stop; leave the database unchanged
The agent cannot see the psql session, so the question says so
(`skill-gates.md` § state): "…on bs? I can't see your session — the
read-back will confirm."
### Step 4: Branch on the answer
- **Done, ran it** → Step 5.
- **Use a different row** → back to Step 1 with the user's
correction; issue a fresh block (never edit the old one in place).
- **Didn't run it** → record that the write is outstanding and
stop; do not continue as if it landed.
### Step 5: Verify
Run a read-back through `dev10x-db:db-psql` that selects the changed
columns with the same WHERE clause. Compare against the intended
end state. A mismatch is a finding to report, never something to
"fix" with another write in the same breath — go back to Step 1.
## Gotchas
**Box-drawing characters break the paste.** The `AskUserQuestion`
widget draws its prompt inside a frame. A statement embedded in the
question arrives in the clipboard with the frame attached:
```
│ UPDATE shop SET is_active = false WHERE id = 4182; │
```
psql rejects it:
```
ERROR: syntax error at or near "│"
LINE 1: │ UPDATE shop SET is_active = false WHERE id = 4182; │
^
```
The user then hand-cleans the line, and hand-cleaning is exactly
where a WHERE clause gets truncated. Keep the SQL in a fenced block
in chat text (Rule 1); the question only points at it.
**A missing header sends the write to the wrong database.** Several
psql sessions are usually open at once. Without
`-- Run against: <alias> (<label>)` on the first line, nothing in
the block says which one it belongs to.
**"Done" is not evidence.** The user may have hit the wrong session,
an open transaction may never have committed, or a trigger may have
rewritten the row. Only the Step 5 read-back is evidence.
## Examples
See [`references/examples.md`](references/examples.md) for a single
UPDATE, an ambiguous-row handoff with a confirming SELECT first, a
"Use a different row" correction, and a hook-blocked write.
## Integration
- **`dev10x-db:db`** — plans the query and verifies table and column
names before the handoff
- **`dev10x-db:db-psql`** — runs the confirming and verifying SELECTs;
its "When a Query Is Blocked" section hands off to this skill
Files in this package (3)
- SKILL.md 6 KB
- evals/evals.json 4 KB
- references/examples.md 3 KB
Versions
The database has no other skills named dev10x-db:sql-handoff.
Database snapshot: 13.11.2026 · package version 3363bc1984be (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100analytics
Run SQL queries against psql, BigQuery, or MySQL from the terminal, including natural-language-to-SQL and schema exploration. Use when analyzing data, inspecting DB state, or debugging tables. Trigger on "query the database", "SQL", "show me data from", "explore table". - 100sql-query-conventions
Read-path SQL conventions for raw SQL, PostgREST, and SQL-shaped ORMs. TRIGGER when: writing or modifying a SELECT query, PostgREST .from()/.select() chain, list-returning ORM call, or query-shape / pagination design. DO NOT TRIGGER when: writing write-path… - 100query-sql
Toolkit for interactively querying and exploring the local PostgreSQL database schema and data using the local psql client. Use when asked to write a SQL query, explore database schemas, inspect table structures, or execute local database queries. Connects as each project's own… - 100frappe-syntax-query-builder
Use when building database queries with frappe.qb in Frappe v14-v16. Covers the PyPika-based query builder: SELECT, INSERT, UPDATE, DELETE, joins, aggregation, subqueries, cross-DB compatibility (MariaDB/PostgreSQL), and migration from raw SQL. Prevents SQL injection and… - 100mysql-sql-review
MySQL 兼容 SQL 审查助手。用户贴出一条或多条 SQL(SELECT/INSERT/UPDATE/DELETE/DDL),希望检查写法是否正确、会不会慢、有没有风险时使用。适用于 MySQL 及 MySQL 兼容数据库(如 OceanBase MySQL 模式、seekdb、TiDB)。按“正确性 → 性能 → 安全 → 可维护性”逐项审查,输出分级问题表、语义等价的改写 SQL 和验证方法;缺少表结构或执行计划时明确标注前提,不臆测。 - 90sql-postgres
Write and review Postgres SQL (DDL, DML, indexes, constraints). Use for .sql, schemas, or Postgres mentions.