Skip to content
Skills Library
Data & analytics · Automation

offshoot

/offshoot

Use when working on a project that has an offshoot store (a .offshoot directory or OFFSHOOT_STORE) and you are about to change a SQLite database — schema migrations, bulk deletes, data experiments, or running several attempts at a fix. Teaches the fork-before-risky-work loop with the offshoot_* MCP tools.

Repository
offshoot ↗
Licence
Apache-2.0
Last repository change
17.10.2026

Assessment and security

100/ 100Class: good
Format25 / 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
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

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

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when working on a project that has an offshoot store (a .offshoot directory or OFFSHOOT_STORE) and you are about to change a SQLite database — schema migrations, bulk deletes, data experiments, or running several attempts at a fix. Teaches the fork-before-risky-work loop with the offshoot_* MCP tools.

Original author description

Use when working on a project that has an offshoot store (a .offshoot directory or OFFSHOOT_STORE) and you are about to change a SQLite database — schema migrations, bulk deletes, data experiments, or running several attempts at a fix. Teaches the fork-before-risky-work loop with the offshoot_* MCP tools.

How it works

  1. The loop
  2. Rules
  3. Rules-file snippet for the project's AGENTS.md or CLAUDE.md
Original SKILL.md headings · 85 lines, 724 words
SKILL.md preview
---
name: offshoot
description: Use when working on a project that has an offshoot store (a .offshoot directory or OFFSHOOT_STORE) and you are about to change a SQLite database — schema migrations, bulk deletes, data experiments, or running several attempts at a fix. Teaches the fork-before-risky-work loop with the offshoot_* MCP tools.
---

# offshoot: branch the database before you change it

offshoot gives every attempt its own real SQLite database — a copy-on-write
fork, not a mock and not a re-seed. Every checkout is a stock `.db` file any
SQLite client opens. You have ten tools; the loop is four calls.

## The loop

1. **Orient:** `offshoot_list` — see databases, branches, checkpoints, and
   which branches are protected (`main` is, by default). A human can
   protect any other branch too (`offshoot protect <db>[@branch]` /
   `offshoot unprotect`, CLI-only — there's no MCP tool for it, so you can
   see the flag here but never change it).
2. **Fork before risk:** `offshoot_fork {database, new_branch, branch?, at?, ttl?, meta?}`
   — instant, two small metadata objects, no data copy. Forks expire after
   the server's default TTL (24h) unless you pass `ttl`. Then
   `offshoot_checkout {database, branch: new_branch}` and point your SQL at
   the returned path.
3. **Checkpoint when tests pass:** `offshoot_checkpoint {database, branch, name, meta?}`.
   Name checkpoints for what they mean (`before-migration`, `migrated`).
4. **Roll back when they fail:** `offshoot_rollback {database, branch, to}`
   returns the branch to a checkpoint, discarding everything since. The
   branch's previous head is kept first as `<branch>-pre-rollback` — the
   result's `backup` field names it — so a rollback is undone by promoting
   that fork back onto the branch (`offshoot_promote {source:
   "<branch>-pre-rollback", target: branch}`). Same TTL'd, one-rolling-slot
   shape as promote's own safety fork below.
5. **Compare before you promote:** `offshoot_diff {database, left:
   "attempt-2@done", right: "main"}` (or against a golden checkpoint) — read
   the per-table added/removed/changed counts; use `table` + `full` to see
   the exact rows.
6. **Promote the winner:** `offshoot_promote {database, source, target}`
   repoints `target` (often `main`) at `source`'s head. Protected targets
   (`main` by default) refuse; that refusal is the confirmation step, not a
   bug. Do not retry with `force: true` — this server refuses force too
   unless the operator started it with `offshoot mcp -allow-force`. Instead
   run `offshoot_diff` to show what would change, then ask the human to
   promote from the CLI (`offshoot promote <db>@<source> --onto <target>
   --force`). The target's previous head is kept as `<target>-pre-promote` — the result
   names it — so a promote is undone by promoting that fork back. That
   safety fork always carries a TTL (24h by default) and is one rolling
   slot per target, replaced by the next promote onto that target, so the
   undo window closes when either happens.
7. **Clean up:** `offshoot_destroy` a failed attempt, or let its TTL expire.
   `offshoot_touch {database, branch, ttl?}` keeps a fork alive if a task
   runs long. A protected branch (or one under a live lease) refuses, and
   `force` is refused too unless the operator started
   `offshoot mcp -allow-force` — do not retry with force; ask the human, who
   can destroy from the CLI. A refusal that says another checkpoint is in
   progress (a lease holder starting `checkpoint:`) is the exception: that
   lease ends on its own within seconds, so wait and retry the same call
   rather than asking the human.
   On a long-running branch where you name a checkpoint every step,
   `offshoot_prune_checkpoints {database, branch, keep: 20}` (or `names`)
   drops checkpoints you will not roll back to; it never touches the
   branch's data, and each new checkpoint stays fast.

## Rules

- Never run a migration, `DROP`, `DELETE`, or `UPDATE` without a checkpoint
  or a fork to return to. `/rewind` restores Claude's file edits only; it does
  not undo what a Bash `sqlite3` command did to a database.
- Prefer forking to backing up by hand. Prefer a longer `ttl` to `ttl: "none"`.
- Read results: `structuredContent` carries `txid`, `path`, `ttl`, `backup`
  for you to reuse; the text is the same information for the human.
- If a tool says a daemon session is open on a branch, close it first
  (`offshoot session close`) rather than forcing. If it says the session
  is closing ("closing; retry"), do not close it: wait a few seconds and
  call the same tool again.
- Work in the fork's checkout path, not `main`'s, while experimenting.

## Rules-file snippet for the project's AGENTS.md or CLAUDE.md

```
Database changes: this project uses offshoot. Before any schema migration,
bulk delete, or data experiment, fork the database (offshoot_fork) and work
in the fork's checkout; checkpoint when tests pass; roll back when they
fail; promote the fork that worked. Never run destructive SQL on main's
checkout directly.
```

Docs: https://sricola.github.io/offshoot/docs/agents/ · machine-readable index:
https://sricola.github.io/offshoot/llms.txt

Versions

The database has no other skills named offshoot.

Database snapshot: 13.11.2026 · package version b172baf08505 (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

  • 100mcp-server-sqlite
    Use this skill when installing, configuring, and executing tools with the local SQLite file inspection and query execution SQLite MCP server.
  • 95expo-sqlite
    Persist and query local data with expo-sqlite in Expo or React Native apps. Use for SQLite setup, SQL queries, schema migrations, transactions, SQLiteProvider, expo-sqlite/kv-store, or the localStorage polyfill.
  • 100database-inspector
    探索 SQLite 或 PostgreSQL 数据库,执行安全只读查询,提供表列表、详细表结构(列/类型/约束/索引)、数据预览,并生成 Mermaid ER 图。当用户需要查看数据库架构、探索表关系、预览数据、执行只读查询,或提及 schema、ER 图、SQL 查询、数据预览、describe table、数据库探索等关键词时触发。
  • 85SQLite
    Expert guidance for SQLite database with better-sqlite3 Node.js driver including database setup, queries, transactions, migrations, performance optimization, and integration with TypeScript. Use this when working with embedded databases, better-sqlite3 driver, or SQLite operations.
  • 100database-schema
    Implement and review Cursor BYOK SQLite schema changes. Use when adding or changing tables, columns, indexes, constraints, foreign keys, SQLx migrations, persistence mappings, or database fixtures under server.
  • 100sql-toolkit
    Query, design, migrate, and optimize SQL databases. Use when working with SQLite, PostgreSQL, or MySQL — schema design, writing queries, creating migrations, indexing, backup/restore, and debugging slow queries. No ORMs required.

Feedback and reports

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