Skip to content
Skills Library
Programming · Automation

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.

Licence
MIT
Last repository change
08.11.2026

Assessment and security

90/ 100Class: good
Format15 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.11.2026, without references to retired models or APIs.

Licence

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

  1. Orchestration
  2. Overview
  3. The Rules
  4. Workflow
  5. Gotchas
  6. Examples
  7. Integration
Original SKILL.md headings · 154 lines, 896 words
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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.