ckb/.agents/modules/share/skills/ckb-share/SKILL.md
Michał Kopeć 8dc3445b27 Template 1.28.0: share module — mailboxes in a git channel (D-0018)
New opt-in `share` module with skill `ckb-share` and stdlib `share.py`
(join/send/unshare/list/receive/status). KBs exchange documents through a
git channel with one append-only mailbox per KB; sends are packed
self-contained, secret-scanned and confirmed; received documents land in
raw/inbox/ (untrusted), retractions in raw/retractions/; the git author
must own the mailbox. dedup_inbox.py reports SAME SHARE; ckb-ingest and
ckb-retract know share files. Smoke test covers two KBs end to end.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 13:31:51 +01:00

6.4 KiB

name description
ckb-share Send a document from this KB to another Cascade KB through a shared git repo (a channel), and receive what other KBs sent into raw/inbox/ — with versions and retractions. Use for "share X with <kb>", "send this document to <kb>", "check shared mail", "take the shared documents", "what did I share", "join channel X", "unshare X".

Share skill (module: share)

Purpose

A channel is a separate git repo with one append-only mailbox per KB: mail/<kb>/. Only that KB writes there, so the channel never conflicts. A new version or a retraction is a new file. This skill moves messages in and out. It never writes to wiki/ and never ingests. Received documents go through ckb-ingest and its check-in like any other inbox file.

Every command below is <python> .agents/skills/ckb-share/scripts/share.py …, with <python> resolved per "Scripts and the Python Runtime" in AGENTS.md. Pass the session identity as --author "Name <email>" when it differs from git config. Without Python there is no fallback: say so and stop.

Join a channel — "join channel X"

The channel repo must exist on the git host, empty or not. Creating it is the user's job. Ask for its URL, then:

share.py join --channel <name> --url <git-url> [--kb-name <mailbox>]

The mailbox name defaults to the KB folder's slug, and it is fixed once set. The script clones into tmp/share/<channel>/. It seeds CHANNEL.md and members.yaml when they are missing, and registers this KB's mailbox with the session identity as owner. Then it writes the share: block of ckb.yaml. That block belongs to the script: never edit it by hand. If the mailbox already exists and the user is not an owner, say so. Receiving works, but sending needs an existing owner to add them to members.yaml.

Send — "share X with beta"

  1. Find the source. Only Markdown in outputs/documents/, outputs/answers/ or wiki/ can be sent. A raw/archive/ source may be someone else's material. Ask, and add --raw-ok only on a yes. If the user names a topic, find the page first and confirm which one they mean.

  2. Dry run:

    share.py send <path> --to beta[,gamma|*] [--channel <name>] --dry-run
    

    The script packs a self-contained copy into tmp/share/outgoing/. <private> spans and ## Notes are dropped (add --keep-notes only if the user asks for their notes to go). Links into this KB become text, and Sources and Crux paths are marked <kb>:. It prints the channel, recipients, version, what was dropped, and the ABOUT.md Sensitivity section.

    • Exit 3: a possible secret. Nothing was sent and the preview is gone. Name the line and the kind of secret, never the value, and stop. The user fixes the source; never work around the scan.
  3. Judge sensitivity. Read the printed Sensitivity text against the recipient. If it rules the material out (another client, personal data, internal only), say which line and stop unless the user overrides it explicitly.

  4. Ask once, naming everything: "Send “