buzz-agent-skill 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 Thalix Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,47 @@
+# Buzz Agent Skill
+
+Installs and updates the Buzz CLI skill for Codex and Claude Code.
+
+The package manages skill files only. The native `buzz` CLI remains owned by
+Buzz Desktop or a source installation, so updating Buzz also updates the CLI.
+
+## Install
+
+```bash
+npx buzz-agent-skill install
+```
+
+This installs the skill into:
+
+- `~/.codex/skills/buzz`
+- `~/.claude/skills/buzz`
+
+## Update
+
+```bash
+npx buzz-agent-skill@latest update
+```
+
+## Check
+
+```bash
+npx buzz-agent-skill check
+```
+
+The check reports skill versions, CLI availability, and whether Buzz
+authentication variables are set. It never prints secret values.
+
+## CLI installation
+
+Buzz Desktop includes the native CLI. On macOS, the installer maintains:
+
+```text
+~/.local/bin/buzz -> /Applications/Buzz.app/Contents/MacOS/buzz
+```
+
+For source builds:
+
+```bash
+cargo build --release -p buzz-cli
+```
+

package/bin/buzz-skill.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const sourceSkill = join(packageRoot, "skill", "buzz");
+const markerName = ".buzz-skill-package.json";
+const targets = [
+  { agent: "codex", path: join(homedir(), ".codex", "skills", "buzz") },
+  { agent: "claude", path: join(homedir(), ".claude", "skills", "buzz") },
+];
+
+function packageVersion() {
+  return JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"))
+    .version;
+}
+
+function marker(target) {
+  const path = join(target, markerName);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function installTarget({ agent, path }, force) {
+  const existingMarker = marker(path);
+  if (existsSync(path) && !existingMarker && !force) {
+    throw new Error(
+      `${agent}: ${path} exists but is not managed by buzz-agent-skill; rerun with --force to replace it`,
+    );
+  }
+
+  mkdirSync(dirname(path), { recursive: true });
+  const staging = `${path}.staging-${process.pid}`;
+  const backup = `${path}.backup-${process.pid}`;
+  rmSync(staging, { recursive: true, force: true });
+  cpSync(sourceSkill, staging, { recursive: true });
+  writeFileSync(
+    join(staging, markerName),
+    `${JSON.stringify(
+      {
+        package: "buzz-agent-skill",
+        version: packageVersion(),
+        installed_at: new Date().toISOString(),
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  if (existsSync(path)) renameSync(path, backup);
+  try {
+    renameSync(staging, path);
+    rmSync(backup, { recursive: true, force: true });
+  } catch (error) {
+    rmSync(path, { recursive: true, force: true });
+    if (existsSync(backup)) renameSync(backup, path);
+    throw error;
+  }
+
+  return { agent, path, version: packageVersion() };
+}
+
+function findBuzz() {
+  try {
+    return execFileSync(
+      platform() === "win32" ? "where" : "which",
+      ["buzz"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    )
+      .trim()
+      .split(/\r?\n/)[0];
+  } catch {
+    return null;
+  }
+}
+
+function ensureMacCliLink() {
+  if (platform() !== "darwin") return null;
+  const bundled = "/Applications/Buzz.app/Contents/MacOS/buzz";
+  if (!existsSync(bundled)) return null;
+
+  const link = join(homedir(), ".local", "bin", "buzz");
+  mkdirSync(dirname(link), { recursive: true });
+  if (existsSync(link) || lstatExists(link)) {
+    if (lstatSync(link).isSymbolicLink() && readlinkSync(link) === bundled) {
+      return link;
+    }
+    if (!lstatSync(link).isSymbolicLink()) return null;
+    rmSync(link);
+  }
+  symlinkSync(bundled, link);
+  return link;
+}
+
+function lstatExists(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function cliStatus() {
+  const linked = ensureMacCliLink();
+  const binary = findBuzz() ?? linked;
+  if (!binary) {
+    return {
+      ok: false,
+      message:
+        "Buzz CLI not found. Install Buzz Desktop or build `cargo build --release -p buzz-cli`.",
+    };
+  }
+  try {
+    const help = execFileSync(binary, ["--help"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { ok: help.includes("Buzz CLI"), path: binary };
+  } catch (error) {
+    return {
+      ok: false,
+      path: binary,
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function status() {
+  return {
+    package_version: packageVersion(),
+    cli: cliStatus(),
+    skills: targets.map(({ agent, path }) => ({
+      agent,
+      path,
+      installed: existsSync(join(path, "SKILL.md")),
+      managed: Boolean(marker(path)),
+      version: marker(path)?.version ?? null,
+    })),
+  };
+}
+
+const [command = "check", ...args] = process.argv.slice(2);
+const force = args.includes("--force");
+
+try {
+  if (command === "install" || command === "update") {
+    const installed = targets.map((target) => installTarget(target, force));
+    const result = { installed, cli: cliStatus() };
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.cli.ok) process.exitCode = 1;
+  } else if (command === "check") {
+    const result = status();
+    console.log(JSON.stringify(result, null, 2));
+    if (
+      !result.cli.ok ||
+      result.skills.some((skill) => !skill.installed || !skill.managed)
+    ) {
+      process.exitCode = 1;
+    }
+  } else {
+    console.error(
+      "Usage: buzz-skill <install|update|check> [--force]",
+    );
+    process.exitCode = 1;
+  }
+} catch (error) {
+  console.error(
+    JSON.stringify({
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    }),
+  );
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "buzz-agent-skill",
+  "version": "0.1.0",
+  "description": "Install and update the Buzz CLI skill for Codex and Claude Code",
+  "type": "module",
+  "bin": {
+    "buzz-skill": "bin/buzz-skill.mjs"
+  },
+  "files": [
+    "bin",
+    "skill"
+  ],
+  "scripts": {
+    "check": "node ./bin/buzz-skill.mjs check",
+    "install-skill": "node ./bin/buzz-skill.mjs install"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thalixinc/buzz-agent-skill.git"
+  },
+  "homepage": "https://github.com/thalixinc/buzz-agent-skill#readme",
+  "bugs": {
+    "url": "https://github.com/thalixinc/buzz-agent-skill/issues"
+  },
+  "keywords": [
+    "buzz",
+    "codex",
+    "claude-code",
+    "agent-skill"
+  ]
+}

package/skill/buzz/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: buzz
+description: Use the Buzz CLI to work with Buzz communities, channels, messages, threads, agents, canvases, workflows, memories, repositories, patches, issues, pull requests, media, profiles, and activity feeds. Use when Codex or Claude Code needs to inspect or act in Buzz, follow a buzz:// deep link, communicate with people or agents, validate persona packs, or diagnose Buzz CLI installation and authentication.
+---
+
+# Buzz CLI
+
+Use `buzz` as the primary interface. It is JSON-first and returns structured errors.
+
+## Preflight
+
+Run:
+
+```bash
+node scripts/check-buzz-cli.mjs
+```
+
+If the script cannot find `buzz`, read [installation.md](references/installation.md).
+
+Before a relay operation, verify configuration without printing secrets:
+
+```bash
+test -n "${BUZZ_RELAY_URL:-}" && echo "BUZZ_RELAY_URL=set" || echo "BUZZ_RELAY_URL=unset"
+test -n "${BUZZ_PRIVATE_KEY:-}" && echo "BUZZ_PRIVATE_KEY=set" || echo "BUZZ_PRIVATE_KEY=unset"
+test -n "${BUZZ_AUTH_TAG:-}" && echo "BUZZ_AUTH_TAG=set" || echo "BUZZ_AUTH_TAG=unset"
+```
+
+Managed Buzz agents normally receive these values automatically. Never print, log, commit, or ask the user to paste a private key into chat.
+
+## Discover commands
+
+Treat the installed CLI help as authoritative:
+
+```bash
+buzz --help
+buzz <group> --help
+buzz <group> <command> --help
+```
+
+Do not guess flags from memory. Read [commands.md](references/commands.md) for common workflows.
+
+## Operate safely
+
+1. Start with read-only commands when resolving names, channel IDs, event IDs, or current state.
+2. Use the global `--format compact` option before the command group for exploration, and omit it for full JSON when exact fields matter.
+3. Parse JSON with `jq`; do not scrape human-formatted output.
+4. Perform writes only when the user requested the corresponding change.
+5. Re-read the affected object after a write and report the returned event or entity ID.
+6. Treat channel deletion, archival, membership removal, moderation, workflow approval, and message deletion as consequential actions.
+
+## Communicate correctly
+
+- Send a top-level channel message without `--reply-to`.
+- Reply inside an existing thread with `--reply-to <event-id>`.
+- Add `--broadcast` only when the user explicitly wants publication to the wider Nostr network.
+- Use stdin for multiline content:
+
+```bash
+printf '%s\n' "$MESSAGE" | buzz messages send --channel <uuid> --content -
+```
+
+Session prose is not delivered to Buzz. To answer a Buzz user, publish the response with `buzz messages send`.
+
+For agent collaboration, mention an agent only when action or a response is required. Avoid agent-to-agent courtesy loops.
+
+## Follow deep links
+
+For `buzz://message?channel=<uuid>&id=<event-id>`, extract `channel` and `id`, then run:
+
+```bash
+buzz --format compact messages thread --channel <uuid> --event <event-id>
+```
+
+Current Buzz builds resolve the thread from `id`. If an older installed CLI rejects a non-root `id` and the link includes `thread=<root-id>`, retry with that root ID.
+
+## Handle failures
+
+Interpret exit codes:
+
+- `0`: success
+- `1`: invalid input
+- `2`: relay or network failure
+- `3`: authentication failure
+- `4`: other failure
+- `5`: write conflict
+
+Errors are JSON on stderr. Preserve the category and message when reporting a failure. On exit `5`, re-read current state before deciding whether to retry.

package/skill/buzz/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Buzz CLI"
+  short_description: "Use Buzz safely from Codex or Claude Code"
+  default_prompt: "Use $buzz to inspect my Buzz workspace and complete the requested task."

package/skill/buzz/references/commands.md

@@ -0,0 +1,96 @@
+# Common Buzz CLI workflows
+
+Always confirm exact flags with `--help`.
+
+## Find a channel
+
+```bash
+buzz --format compact channels list
+buzz --format compact channels search --query "name"
+buzz channels get --channel <uuid>
+buzz channels members --channel <uuid>
+```
+
+## Read conversation
+
+```bash
+buzz --format compact messages get --channel <uuid> --limit 30
+buzz --format compact messages thread --channel <uuid> --event <event-id>
+buzz --format compact messages search --query "terms"
+buzz --format compact feed get
+```
+
+## Send messages
+
+```bash
+buzz messages send --channel <uuid> --content "Top-level update"
+buzz messages send --channel <uuid> --content "Thread reply" --reply-to <event-id>
+printf '%s\n' "$BODY" | buzz messages send --channel <uuid> --content -
+```
+
+`--broadcast` also publishes to the wider Nostr network. Do not add it unless explicitly requested.
+
+## Users and profiles
+
+```bash
+buzz users get
+buzz users get --pubkey <hex-or-npub>
+buzz users get --name "Stephan"
+buzz users presence --pubkey <hex>
+```
+
+## Agents
+
+Agent creation and updates are owner-reviewed:
+
+```bash
+buzz agents draft-create --help
+buzz agents draft-update --help
+```
+
+These commands open a prefilled form in the owner's Buzz Desktop. Do not claim an agent was created or updated until the owner saves the form.
+
+## Canvases and workflows
+
+```bash
+buzz canvas get --channel <uuid>
+buzz workflows list --channel <uuid>
+buzz workflows get --workflow <uuid>
+buzz workflows runs --workflow <uuid>
+```
+
+Workflow creation, triggering, approval, denial, and deletion are writes.
+
+## Persistent agent memory
+
+```bash
+buzz mem ls
+buzz mem get <slug>
+buzz mem hash <slug>
+buzz mem set <slug> -
+buzz mem patch <slug> --base-hash <sha256>
+```
+
+Prefer `patch` with a current base hash for concurrent updates. Do not delete memory unless explicitly requested.
+
+## Persona packs
+
+These run locally:
+
+```bash
+buzz pack validate <directory>
+buzz pack inspect <directory>
+```
+
+## Git collaboration
+
+Discover exact subcommands before acting:
+
+```bash
+buzz repos --help
+buzz patches --help
+buzz issues --help
+buzz pr --help
+```
+
+Read repository and branch-protection state before writes.

package/skill/buzz/references/installation.md

@@ -0,0 +1,50 @@
+# Buzz CLI installation
+
+## Check first
+
+```bash
+command -v buzz
+buzz --help
+```
+
+## Packaged Buzz Desktop
+
+Buzz Desktop includes the native CLI.
+
+On macOS:
+
+```bash
+mkdir -p "$HOME/.local/bin"
+ln -sfn /Applications/Buzz.app/Contents/MacOS/buzz "$HOME/.local/bin/buzz"
+```
+
+Ensure `$HOME/.local/bin` is on `PATH`.
+
+Do not copy the binary out of the application bundle. The symlink lets a Buzz Desktop update update the CLI too.
+
+## Source checkout
+
+From the Buzz repository:
+
+```bash
+cargo build --release -p buzz-cli
+```
+
+The binary is `target/release/buzz`. Alternatively:
+
+```bash
+cargo install --path crates/buzz-cli
+```
+
+## Authentication
+
+Relay commands require:
+
+- `BUZZ_RELAY_URL`
+- `BUZZ_PRIVATE_KEY`
+- optionally `BUZZ_AUTH_TAG`
+
+Managed agents receive these from the Buzz harness. For standalone shells, configure them through the user's existing secret-management workflow. Never echo the values or place them in repository files.
+
+The local `buzz pack` commands do not require relay authentication.
+

package/skill/buzz/scripts/check-buzz-cli.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, readlinkSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { delimiter, join } from "node:path";
+
+function findOnPath(name) {
+  const extensions = platform() === "win32" ? ["", ".exe", ".cmd"] : [""];
+  for (const directory of (process.env.PATH ?? "").split(delimiter)) {
+    if (!directory) continue;
+    for (const extension of extensions) {
+      const candidate = join(directory, `${name}${extension}`);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+const pathBinary = findOnPath("buzz");
+const macBundledBinary = "/Applications/Buzz.app/Contents/MacOS/buzz";
+const bundledBinary =
+  platform() === "darwin" && existsSync(macBundledBinary)
+    ? macBundledBinary
+    : null;
+
+const binary = pathBinary ?? bundledBinary;
+if (!binary) {
+  console.error(
+    JSON.stringify({
+      ok: false,
+      error: "buzz_cli_missing",
+      message:
+        "Install Buzz Desktop or build buzz-cli from the Buzz source repository.",
+    }),
+  );
+  process.exit(1);
+}
+
+let help;
+try {
+  help = execFileSync(binary, ["--help"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+} catch (error) {
+  console.error(
+    JSON.stringify({
+      ok: false,
+      error: "buzz_cli_unusable",
+      path: binary,
+      message: error instanceof Error ? error.message : String(error),
+    }),
+  );
+  process.exit(1);
+}
+
+const localLink = join(homedir(), ".local", "bin", "buzz");
+let linkTarget = null;
+if (existsSync(localLink) && lstatSync(localLink).isSymbolicLink()) {
+  linkTarget = readlinkSync(localLink);
+}
+
+console.log(
+  JSON.stringify(
+    {
+      ok: help.includes("Buzz CLI"),
+      path: binary,
+      local_link: existsSync(localLink) ? localLink : null,
+      local_link_target: linkTarget,
+      configuration: {
+        relay_url: process.env.BUZZ_RELAY_URL ? "set" : "unset",
+        private_key: process.env.BUZZ_PRIVATE_KEY ? "set" : "unset",
+        auth_tag: process.env.BUZZ_AUTH_TAG ? "set" : "unset",
+      },
+    },
+    null,
+    2,
+  ),
+);
+