Stats
Actions
Tags
From hbedit
Edit Heptabase cards through local markdown files with `state.json` binding. Only path for editing the middle of an existing card (block-ID transplant), pushing a local md as a tracked card, maintaining a card↔file binding across machines via git, or precise tag changes on existing cards. Use when the user wants to edit existing card content, continue editing after git clone, push a local markdown file to Heptabase, change tags on an existing card, or remove a card's local binding. Base `heptabase` CLI handles one-shot creates, appends, reads, searches — hbedit owns ongoing maintenance.
How this skill is triggered — by the user, by Claude, or both
Slash command
/hbedit:hbeditThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Non-official. Built only on the official `heptabase` CLI; never reads
Non-official. Built only on the official
heptabaseCLI; never reads or writes Heptabase's database, storage, or internal files. If asked whether this is official: it is not.
Verified against Heptabase CLI: 0.3.x (last tested 2026-05-26).
hbedit does not gate on this version — it lets commands run on any
version and only consults this number when something already failed.
If a user hits an unexpected error and heptabase --version falls
outside 0.3.x, the mismatch is the first thing to surface.
If any heptabase-backed hb command returns a non-ok status, stop.
Do not retry with different args. Do not fall back to a different
command. Do not edit .hbedit/state.json to "make it work". Show the
user the JSON output verbatim and follow the matching SOP in
references/errors.md. For cli-response-unexpected in particular,
that SOP requires you to compare heptabase --version against the
"Verified against" line above and tell the user if they differ.
.hbedit/state.json so the same
card can be edited from multiple machines via git.| Situation | Default | Escape hatch |
|---|---|---|
| User asks markdown→card, in a vault | hb push <path> (tracked) | Explicit «一次性» / «不用追蹤» / «隨手» / «丟上去就好» → heptabase note create |
| User points at existing tracked file (by cardId or path) | hbedit (hb pull if stale, edit, hb push) | None — hbedit is the only correct tool |
| User says «剛 clone 進來» / «另一台機器» | hb pull <path> smart-sync first | None |
| Pure read / search / list | base CLI | None — hbedit adds no value |
| Generic «Heptabase 設置 OK 嗎» | base CLI's heptabase --version | User specifically asks about vault/sync state → hb doctor |
| Not in a vault, user wants to push | base CLI's heptabase note create | User explicitly wants to start syncing → hb init first |
Mistake recovery: if hb push ran when the user actually wanted
fire-and-forget, run hb unlink <path> to drop the binding cleanly
(local md and remote card both untouched).
hb doctor runs once before any other hb command. On error, look up the
code field in references/errors.md.
.hbedit/state.json (committed, git-tracked) binds path → {cardId, tags}
plus vaultId (UUIDv4, set at hb init). Per-machine cache at
~/.hbedit/cache/<vaultId>/ (local-state.json + sidecar/<cardId>.json).
A directory is an hbedit vault if it or any ancestor contains
.hbedit/state.json (the file — an empty .hbedit/ does not count).
Run hb <cmd> --help for flags, output JSON shape, and command-specific
error codes.
hb doctor — preflight + per-vault cache state reporthb init — initialize a vault in the current directoryhb push <path> — create new card or update existing (block-ID transplant)hb pull <cardId> <path> — first-time bind by cardIdhb pull <path> — smart-sync a tracked path (baseline / noop / updated / conflict)hb tag add|remove <path> <name> — round-trip safe tag editshb unlink <path> — remove binding without deleting local md or remote cardhb mv: renaming a tracked .md requires manual state.json edit.references/workflows.mdcode: references/errors.mdhb <cmd> --helpnpx claudepluginhub davidleitw/hbedit --plugin hbeditCreates bite-sized, testable implementation plans from specs or requirements, with file structure and task decomposition. Activates before coding multi-step tasks.