davidondrej/skills

# BB CLI

Never inspect or message other threads unless the user explicitly requests that action.

Use bb for BB state and actions. Inspect the current context before you choose
IDs, machines, workspaces, providers, or models.

## Start with context

```sh
bb status --json
```

Use JSON when command output controls later work. Use human output for quick

# bb plugins

bb plugins are TypeScript packages that run inside bb. They are how bb extends itself.

Many first-party features are plugins: GitHub, Docs, Memory, Tasks, Connect, Automations, Secrets, Keep Awake, and the coding-agent providers.

## Trust

Plugins are full-trust. Server code runs in-process. App UI is same-origin page code, not a sandbox. Host workers run as Node on enrolled machines.

[Credential-related source omitted]

## This skill vs others

# cmux Control

macOS 14.0+. Prefer the CLI; if `cmux` is not on PATH, use `/Applications/cmux.app/Contents/Resources/bin/cmux`.

## Targeting and safety

**Window → workspace → pane → surface:** macOS window → sidebar project/branch tab → split region → terminal, browser, or Markdown tab.

- **Anchor to the caller's `CMUX_WORKSPACE_ID`.** Never assume the visually focused workspace is the target. Outside cmux, identify the intended workspace before acting.
- **Use prefixed refs or UUIDs.** `workspace:2`, `pane:1`, `surface:7`; bare numbers are indexes, not IDs. Output defaults to refs; `--id-format uuids|both` includes UUIDs.
- **Refresh targets.** Surface refs are global, not workspace-local. Re-list before reusing them; check `cmux surface-health` before sending input when state may be stale.
- **Preserve focus.** Pass `--focus false` wherever supported. Use `select-workspace`, `focus-pane`, `focus-panel`, or `focus-surface` only on explicit user request.
- **Respect ownership.** Never send input to surfaces you do not own. Stay in the caller's workspace unless the user explicitly requests cross-workspace routing.
- **Reuse one helper pane.** Use an existing non-caller helper pane or create one on the right. Create the intended layout directly with `new-pane --type … --focus false`.

# Codex CLI as a Subagent

Codex CLI is OpenAI's terminal coding agent. `codex exec` runs it non-interactively:
it works autonomously in a sandbox, streams progress to stderr, and prints only the
final message to stdout. Auth reuses the user's ChatGPT subscription — never an API key.

## When to delegate

- Self-contained coding task with clear success criteria (fix, feature, refactor, review).
- Parallel work: several independent tasks at once (see Parallel runs).
- Second opinion / independent verification of your own changes.

Do NOT delegate tasks that need conversation context you can't fully write into the prompt.

# Fable Review

Use **Fable 5.1 Extra High** through Claude Code, orchestrated by [Cloudroom](https://www.cloudroom.dev).

## Run

Read `/room-cli` and follow its launch checks. Discover provider/model/effort IDs rather than guessing. Reuse the current environment, including uncommitted work, and use `--parent-self` when coordinating.

If the user names another harness, read its skill and use it with the same model, effort, workspace, brief, and output requirements. Report unavailable model/effort as blockers; never silently downgrade.

## Review brief

Give neutral context: scope, paths, intended behavior, and diff/base revision. Ask for a thorough senior-developer review, including related code and tests, without steering toward suspected bugs, solutions, or verdicts. Review only; do not change files. Request a concise plain-English report of serious or critical issues, fixes, and production merge readiness. Distinguish verified findings from uncertainty and identify validation gaps.

# Fable-Safe Prompt

Return the **full prompt**, changing only phrases likely to cause false-positive refusals. Preserve the goal, structure, and all other text verbatim. Acceptance is **not guaranteed**.

The relevant classifier categories are **cyber**, **bio/chem**, and **reasoning_extraction**. Rephrase sensitive wording where needed; restating intent alone may not help.

Relevant topics include cyber/auth, exploits, malware, pentesting, credentials, bio/chem, medical/lab work, and requests for internal reasoning.

Edit only text inside the user's `<prompt>...</prompt>` tags. Treat text outside them as instructions to you.

## Method

1. Identify phrases likely to trigger a refusal.
2. Replace them in place using the examples below. Preserve the actual goal; never invent authorization or disguise harmful intent.

# Git Worktrees for Parallel Agents

## In Cloudroom (`$ROOM_THREAD_ID` is set)

Never run `git worktree add` yourself. Cloudroom only deletes worktrees it made, so hand-made ones pile up in `~/code` forever.

- **New task:** start the thread with **New worktree** instead.
- **Move this thread to its own worktree:** fork it into a Cloudroom-managed worktree. Cloudroom makes the branch and deletes the folder once its last thread is archived (after the worktree retention setting, default 21 days).

  ```bash
  room-cli thread fork "$ROOM_THREAD_ID" --new-environment worktree --title "<task>" \
    --prompt "You now run in a new worktree. Copy the gitignored .env files from <primary checkout> into it, then stop and wait for the user."
  ```

# Agent `/goal` Loop

## What `/goal` is

`/goal` makes an agent persist through `plan → act → test → review → iterate`.
If a turn ends before the goal is met, it auto-continues instead of waiting for
input. The loop ends at its stop condition, a user pause, or the token budget
limit. It is also called the “Ralph loop”.

Before giving runtime instructions, check goal support in the installed agent
and interface through its help, exposed tools, or current official documentation.
Verify feature flags, authentication, and limits; do not transfer one agent's
requirements to another. Lifecycle states, budgets, and pause/resume vary by runtime.

# GPT Review

Always use **GPT-6-Astra** through Codex, orchestrated by [Cloudroom](https://www.cloudroom.dev). Default to **Extra High reasoning on the Fast tier**. Use another effort or tier only when the user explicitly asks. Never use another model.

## Run

Read `/room-cli` and follow its launch checks. Reuse the current environment, including uncommitted work, and use `--parent-self` when coordinating.

Spawn with these default flags:

```bash
--provider codex --model gpt-6-astra --reasoning-level xhigh --service-tier fast
```

# Handoff

Capture the context a fresh agent needs to continue without re-asking, re-discovering, or repeating mistakes.

## Core Principles

1. **Describe state.** Write "Auth is implemented; logout is not started," not "Implement logout next." The next agent chooses actions from the context.
2. **Link existing artifacts.** Reference PRDs, plans, ADRs, issues, commits, diffs, and design docs by path or URL instead of copying their content.
3. **Preserve why.** Capture decisions, rejected approaches, and failures that code alone cannot explain.
4. **Require verification.** Present claims as context to check against the actual code, not facts to trust blindly.
5. **Redact secrets and PII.** Never include keys, tokens, passwords, or personal data. Name credential locations (e.g. ".env.local, not committed"), never values.
6. **Keep only useful context.** Omit obvious, redundant, or explanatory material recoverable from code or project configuration.

## Procedure

# Herdr

Herdr's CLI controls terminal panes through a local socket; it provides neither native agent-to-agent communication nor shared memory. It works with Pi, Codex, Claude Code, Cursor CLI, and other terminal agents. Native integrations improve detection, status accuracy, and session restoration.

## Preconditions

Run the controlling agent inside Herdr in Ghostty. Verify access and workspace scope:

```bash
test "${HERDR_ENV:-}" = "1"
test -n "${HERDR_WORKSPACE_ID:-}"
```

If either fails, tell the user this agent must be launched inside Herdr; do not claim access to other agents.

# Kimi Review

Always use **Kimi K3.1 Pro at Max reasoning**, orchestrated by [Cloudroom](https://www.cloudroom.dev). The model and effort never change. Only the harness or route may change, and only to get the review running.

## Routes

Try these in order. Move to the next one only when the current one fails.

1. `--provider pi --model vercel-ai-gateway/moonshotai/kimi-k3.1-pro --reasoning-level max`
2. `--provider acp-fx --model moonshotai/kimi-k3.1-pro --reasoning-level max` (fx uses Vercel AI Gateway)
3. `--provider acp-opencode --model vercel/moonshotai/kimi-k3.1-pro --reasoning-level max`
4. `--provider pi --model openrouter/moonshotai/kimi-k3.1-pro --reasoning-level max`
5. `--provider acp-opencode --model openrouter/moonshotai/kimi-k3.1-pro --reasoning-level max`

# Larp Detector

When reviewing this code, be careful. A lot of people on public repos just use an AI coding agent to contribute to a codebase, only for the sake of their name being on the contributors list. They also have no taste and no product feel. They're not trying to fix any real issue, any real problem, or any real bug. They literally just want to contribute.

Another common thing they do is use an AI coding agent to analyze the repo for issues, problems, and security vulnerabilities. Even if our code is good, LLMs will hallucinate hypothetical issues that would really never happen.

So be careful when reviewing this. Check that it is actually a good idea, and think about the intention of the creator. What is the intention? Did they actually face a problem and then tell their coding agent to fix it? Everybody uses AI coding agents, so that alone is not a red flag.

Really try to figure out the intention and the origin of this PR, issue, or whatever you are reviewing:

- Did it come from an actual bug that a user encountered?
- Did it come from genuine care for the product and a really good idea for how to improve it?
- Or is it just a fake improvement, or support for something we don't need?
- Or does it try to fix issues that were artificially found by an LLM, but would never happen given the existing usage patterns of existing users?

# Muse Review

Always use **Meta Muse Wonder at Max reasoning** through the Pi harness and the `openrouter` provider, orchestrated by Cloudroom. No other model, route, effort, or harness, ever. Only OpenRouter offers `max` for this model; Pi sends it through unchanged.

## Run

Read `/room-cli` and follow its launch checks. Reuse the current environment, including uncommitted work, and use `--parent-self` when coordinating.

Always spawn with exactly these flags:

```bash
--provider pi --model openrouter/meta/muse-wonder --reasoning-level max
```

# nagent

Read this before `bb thread spawn`. Use `bb-cli` for other thread operations.

## Defaults

Use Codex `gpt-5.6-sol`, reasoning `high`, service tier `fast` ("GPT 5.6 Sol High Fast"). Use `xhigh` for larger refactors. The user's explicit choices override these defaults.

For a different requested model, use its catalog `defaultReasoningEffort` when unspecified, and enable fast only when asked. Do not infer a higher reasoning level from the model name.

Prefer bare `bb`; `"$BB_CLI"` is also valid when set.

## Look Up the Target

# New Grok Bot

Design a Grok Bot role and produce a prompt to paste into the app. Apply the **unit-of-work test** before drafting.

## Product context (last verified 2026-08-30)

Refresh through the deepapi skill (scrape x.ai/bot) only if something looks outdated or the user asks. Do not auto-refresh.

- Grok Bots are always-on AI teammates from SpaceXAI + Cursor. All Bots on an account share one persistent cloud computer with a browser, filesystem, terminal, and logins. They use real apps and websites, including those without APIs, and work while the user's laptop is closed.
- Bots retain preferences, voice, edge cases, and when to ask versus continue. Teach-a-task saves a demonstrated workflow as a routine to repeat independently or on a schedule.
- Bots can message each other, share context, and coordinate in group chats. A Chief of Staff can coordinate specialists.
- Bots choose plugins or browser interaction themselves; there is no model selection. Plugins include Gmail, Notion, Slack, Google Drive, and custom integrations. Purchases can use a connected payment link.
- Separate Bots are **not security boundaries**: they share files, sessions, and logins.
- Distinguish Grok Automations (scheduled/triggered prompts), Grok Build (terminal coding agent), and @grok on X (reply bot).

# Reset Cursor ACP in your chat app

For terminal sessions use `cursor-cli`; for general app control use `<app-cli>`.

## How resets work

- The app's ACP integration starts one `cursor-agent acp` subprocess per thread, on demand.
- There is no global Cursor ACP server. Do not create one or keep it alive with a watchdog.
- Rules, skills, and `.cursor/mcp.json` reload when a new subprocess starts.
- Use the app's thread-stop command with the thread ID to release the runtime and stop its subprocess while preserving history. The next message starts a fresh agent.

## Quick reset

Resolve `<reset-script>` relative to this `SKILL.md`. Run:

# Self-archive

Act only on an explicit request to archive this thread. Never delete the thread or target unrelated threads.

1. Send a brief closing summary before running commands.
2. Archive the current thread and its children: `room-cli thread archive --self --json` (Local and Cloud).
3. If the command fails, report the error and keep the runtime running. Do not claim the thread was archived.
4. After success, run nothing else. Archiving stops the thread's runtime. In Cloud, the request is recorded durably and the app applies it when it next connects.

To restore the thread, the user can use Cloudroom's UI or run `room-cli thread unarchive <id> --json` on their computer.

# Total Review

Five reviewers, each in its own [Cloudroom](https://www.cloudroom.dev) thread: the two best models from Anthropic and from OpenAI, plus Meta's Muse Wonder, all at their highest effort and in **full permission mode** (the harness maximum). Never swap or downgrade a model, effort, or permission mode. If one is unavailable, stop and tell the user.

## Permissions

Always spawn with `--permission-mode full`. That is Claude Code's bypass permissions (`--dangerously-skip-permissions`) and Codex's YOLO mode (no approvals, `danger-full-access` sandbox). A child cannot exceed its parent, so if this thread is not in full mode, stop and tell the user.

## Reviewers

- **Fable 5.1**: `--provider claude-code --model claude-fable-5-1`
- **Opus 5.5 (1M)**: `--provider claude-code --model 'claude-opus-5-5[1m]'`
- **GPT-6 Astra**: `--provider codex --model gpt-6-astra`
- **GPT-6.1 Sol**: `--provider codex --model gpt-6.1-sol`

# Anti-Sleep (macOS caffeinate)

Use the bundled launcher from this skill directory. It creates a one-shot user LaunchAgent using only built-in macOS tools.

## Required workflow

Never launch `caffeinate` with raw `&`, `nohup`, `disown`, or `launchctl submit`. Temporary execution shells can kill their descendants, and `launchctl submit` can restart a timed job.

Resolve `scripts/anti-sleep.sh` relative to this `SKILL.md`; never assume the user's current directory. Run:

1. Inspect current state:

```bash
scripts/anti-sleep.sh status

# Boat

Manage machines through the API or CLI; use SSH or the command API inside a VM. Before direct API calls, credential changes, or recovery, read [operations and observations](references/operations.md), including its authentication example.

## Box to Boat migration

Use `boat`, `https://boat.dev/api/v1`, `/sandboxes`, and the API key for current examples. Docs live at `https://docs.boat.dev`. Existing projects may still use Box names; inspect their configuration before migrating. Renaming this skill does not authorize changing installed tools, deployed applications, or credentials. See [migration notes](references/operations.md#box-to-boat-migration).

## Identify the account and target

1. Read project instructions and operational notes. Verify the account, organization, sandbox, and repository; reuse existing mappings instead of provisioning duplicates.
2. Load the API key from the environment or the project's documented, gitignored credentials file. Do not assume a universal path, search unrelated credential stores, or print credentials. Use the secrets skill for a new key.
3. Check authentication and state with `GET /me`, `/limits`, and `/sandboxes`, or CLI `boat status`, `boat list`, and relevant `--help`. Filter output to needed fields.
4. Check installed tools. API calls need no Boat CLI or SDK. If installation is needed, read official instructions; never execute a remote installer blindly.

# Create a Read-Only DB Role for Agents

Prepare a SELECT-only role and protected connection. The SQL, role name, grants, denylist, RLS setting, timeouts, and connection steps are examples to adapt to your system, not live production configuration.

## Access model

1. **SELECT-only grants.** Grant no write permissions; use a denylist to exclude secrets and PII.
2. **Current and future tables.** Grant SELECT on all tables in `public`, including future tables through default privileges, then revoke denylisted tables. Never grant the `auth` schema. New sensitive tables need a manual revoke.
3. **Soft guardrails.** Set `default_transaction_read_only = on` and a short `statement_timeout` suited to the workload.

**RLS:** tables may return no rows when the role has no applicable policy. Consider `bypassrls` only if it fits your security model: it skips row filtering, while grants and the denylist still apply.

## Workflow

# Cua Driver

Cua Driver is an MIT-licensed local automation tool, not a model. Pi or another
agent supplies the reasoning; the driver reads accessibility trees/screenshots
and sends input to apps. No Cua cloud account or VM is needed. Host control is
not sandboxed, and desktop content sent to a cloud model leaves the machine.

## Before acting

```bash
command -v cua-driver
cua-driver --version
cua-driver status
cua-driver permissions status --json

# GitHub Outside Sandbox

1. Start normally. Escalate only the blocked command and only within the user's authorization.
2. If sandboxed `gh auth status` fails, rerun it outside the sandbox before claiming authentication is broken. Never expose or copy tokens.
3. Run GitHub CLI network operations outside the sandbox when required: `gh repo ...`, `gh pr ...`, and related `gh` commands.
4. Run Git writes outside the sandbox when `.git` is outside writable roots or errors mention `index.lock` or `Operation not permitted`: `git add`, `git commit`, and `git push`.
5. Use the harness's official host-execution mechanism. In Codex, set `sandbox_permissions: "require_escalated"`, give a concrete `justification`, and use only a narrow safe `prefix_rule` when appropriate.
6. Never use shell wrappers, credential copying, or broad approval prefixes to bypass the sandbox.
7. Verify from the host context with `git status -sb`, `git remote -v`, and the relevant `gh ... view` command. Ask the user to authenticate only if the host-context check also fails.

# Global Agent Guardrails

Block catastrophic shell commands before execution. One patterns file feeds a shared hook script or native adapter for each agent. This guards against accidents, not malicious agents (obfuscation like `python -c "shutil.rmtree(...)"` can slip past regex).

[Cloudroom](https://www.cloudroom.dev/security) ships a built-in Command Guard based on this one, on by default.

## File map

The setup consists of a shared pattern list, a guard script, a test suite, and agent-specific adapters. Keep those in the appropriate user-level configuration locations for your tools.

## Check installation

Confirm the shared guard and patterns are present, then run the test suite; it should report no failures.

# OpenRouter

Make model behavior explicit. Preserve the user's quality, cost, privacy, and reliability requirements across every route and retry.

## Before changing configuration

1. Inspect the actual outgoing request, SDK version, existing configuration, and user preferences. Redact credentials and content. A setting in a UI or config file does not prove the SDK sends it.
2. Verify exact model IDs and live capabilities through the [models API](https://openrouter.ai/api/v1/models). Inspect the selected model's provider endpoints too. Check input/output modalities, context and output limits, supported parameters, reasoning options, prices, and provider availability for **both primary and fallback models**.
3. Choose and record an explicit reasoning setting for each reasoning model. Use the user's requested effort. If unspecified, choose a supported value for the task and state the choice; do not silently inherit a provider default or impose one effort on every model. Read [reasoning and output](references/reasoning-and-output.md) before setting these fields.
4. Set an output ceiling, total deadline, bounded retry policy, and cost limits appropriate to the workload. Reasoning uses output tokens too. A model's context window is not its maximum output length.
5. Read the relevant reference below. Consult current official docs for unfamiliar fields; do not invent model IDs, provider slugs, parameter support, or SDK syntax.

## Rules that prevent expensive mistakes

# Persistent localhost servers (macOS launchd)

One script does everything. Resolve `scripts/persistent-localhost.sh` relative to this `SKILL.md`, never from the current directory.

## Workflow

1. Check what already exists:

```bash
scripts/persistent-localhost.sh list
```

2. Start the server. `--name` is the handle. `--port` enables readiness checks and duplicate handling. `--dir` defaults to the current directory.

# Prompt For Others

Write for an AI agent on a teammate's machine with no chat context. The teammate may be non-technical and will not edit the prompt.

## Workflow

1. Test the fix on the user's machine unless already tested. Never include untested commands.
2. Draft the paragraph in this exact order:
   - **Goal** in one sentence.
   - **Context** in 1–2 sentences: what the tool does, the problem, and why the fix is needed.
   - **Steps** as exact commands, in backticks, in order.
   - **Verify** with exact commands and expected output.
   - **Stop rule**: what to do if a precondition is missing.
   - **Report back**: the 1–2 facts the teammate should receive.

# Rename process

Finish the requested rename with the smallest verified set of changes. Use one coordinator working outside the directory being renamed. Keep existing approvals; ask only for missing decisions or authorization.

## Keep the scope small

- Touch only systems affected by the changed name or path. Keep unrelated Git pulls/rebases, cleanup, dependency updates, document reconciliation, and implementation separate.
- Preserve the existing repository, local work, ignored files, credentials, stashes, worktrees, and conversation identities. A repository split requires explicit scope for the new repository and its visibility/content.
- Keep product branding, domains, runtime/plugin identities, and historical documents unchanged unless their change is requested or necessary. Avoid bulk replacement of every old-name occurrence.
- Use current supported commands. Do not build a general migration framework, launch extra agents, or require a shutdown/database migration without a concrete need.

## Execute

1. **Confirm the map.** Record old/new names, exact real paths, Git remotes, repository identities/visibility, and affected machines. Inspect existing destinations, local changes, aliases, worktrees, services, and tool references. Resolve only missing scope; do not restart an already-approved naming discussion.

# repo-sync

## What it does

Sync shared Git repos for team documents, notes, skills, and context on macOS. Complex software projects and pull request workflows are outside scope.

By default, after 60 seconds without local edits, repo-sync commits eligible non-ignored changes (including staged edits, renames, and deletions), rebases, and pushes. It checks remote changes every 60 seconds and starts at login without an AI agent.

Only the remote's default branch syncs (`origin/HEAD`, falling back to `main`). Feature branches and detached HEAD are skipped; branches are never switched.

## Check first

```sh
command -v repo-sync

# Risky Changes

A filter once passed every test but disabled ~99% of the feature on live data. Tests check code correctness; research and live measurement check whether a change is useful.

## When this applies

Use for changes where being wrong is expensive or customer-visible:

- Public API fields, filters, or response shaping
- Dropping, transforming, or reordering upstream data
- Billing, pricing, caps, or quotas
- Defaults, thresholds, or provider request parameters
- Unverified assumptions about external data or user behavior

# setup-help

Guide the user through any setup, one step at a time, in plain English.

## Response format (every single response)

1. **Current step** — ONE coherent setup step. Group tightly related actions and fields from the same form or screen, and provide every value the user needs to complete them. Use 1–4 concise lines. Split only at a real decision, verification point, or screen change.
2. A `----` divider.
3. **Still remaining** — a numbered list of the setup steps left after this one. Max 8 items, ever. Each item is a HEADLINE only: a few words, easy to glance at. No commands, URLs, event names, values, or explanations — that detail appears only when the item becomes the Current step.

Repeat this format for every response until setup is done.

## Rules

# browser-harness

Direct browser control via CDP. For task-specific edits, use `agent-workspace/agent_helpers.py`. For setup, install, or connection problems, read install.md.

**Routing check first:** if the task needs no interaction (no clicks, logins, or forms) and you just want page content, use DeepAPI `POST /v1/scrape/website` instead of driving a browser — see the `deepapi` skill. Use browser-harness when the task needs a real browser: interaction, JS-heavy flows, logged-in sessions, or visual verification.

Domain skills (community-contributed per-site playbooks under `agent-workspace/domain-skills/`) are off by default. Set `BH_DOMAIN_SKILLS=1` to enable them; see the bottom section.

**If `BH_DOMAIN_SKILLS=1` and the task is site-specific, read every file in the matching `agent-workspace/domain-skills/<site>/` directory before inventing an approach.**

## Usage

```bash
browser-harness -c '

# Browser Use

Direct browser control via CDP. For task-specific edits, use `agent-workspace/agent_helpers.py`. For setup, install, or connection problems, read https://github.com/browser-use/browser-harness/blob/main/install.md.

## When Not to Use

A basic fetch of public information needs no browser. If a plain HTTP request can read it — a public page, an API, docs — use `curl` or your fetch tool, and leave the browser alone. Use browser-use when the task needs interaction (click, type, navigate), the user's logged-in session, JS rendering, or a bot-protected page. If a direct fetch fails or returns a shell page, then escalate to the browser.

Domain skills are off by default. Set `BH_DOMAIN_SKILLS=1` to enable them; see the bottom section.

**If `BH_DOMAIN_SKILLS=1` and the task is site-specific, read every file in the matching `$BH_AGENT_WORKSPACE/domain-skills/<site>/` directory before inventing an approach.**

## Usage

# Deep Research

Use DeepAPI (`POST /v1/research/deep`) for all deep research.

## API key

Read `API_KEY` from the environment.

```bash
KEY=$API_KEY
BASE=${DEEPAPI_API_BASE_URL:-https://deepapi.co}
```

If the key is missing, stop and ask the user. Never print or log it. Get a key at deepapi.co.

# Deep Scrape

Collect structured evidence about one subject across public sources. Use
`deep-research` for detailed answers or recommendations, and a dedicated scraper
for one known page or platform.

## Prepare the request

Read [deepapi](../deepapi/SKILL.md) for credentials, headers, and shared protocol.
Use `POST /v1/scrape/deep` with an API key scoped to `scrape:deep`.

- `query`: required, **500 characters maximum**. Name one subject, add identifying
  context, and state needed information; keep longer instructions for your synthesis.
- `urls`: optional public website/profile seeds to reduce namesake mistakes.

# DeepAPI

This file is a compact router. The `references/` files are organized by user workflow — research, scraping, email, browser automation, image generation, and agent state — not by platform. Read the matching reference for outcome guidance and endpoint detail before your first call in that workflow during a session.

## Required Environment

- Read `DEEPAPI_API_BASE_URL` and `API_KEY` from the environment.
- If either is missing, load the platform file and re-check: PowerShell `. "$HOME/.deepapi/env.ps1"`; bash/zsh `source ~/.deepapi/env`.
- If still missing, stop and ask the user to run the setup prompt from https://deepapi.co/docs.
- Never commit, print, log, paste, or expose `API_KEY`.

## Request Rules

- Send the documented authentication credentials on every request.

# Domain checker

Run the bundled Python 3 checker without packages, credentials or a browser. Resolve `scripts/check_domains.py` relative to this SKILL.md, regardless of the working directory.

```sh
python3 <skill-dir>/scripts/check_domains.py example.com example.dev example.ai --json
```

Use complete domains, not bare brand names or URLs; expand each name/TLD combination. Only domains directly under a TLD are supported (e.g. `.com`, `.dev`, `.ai`, `.cloud`), not multi-label suffixes such as `.co.uk`.

The script discovers endpoints through IANA and queries public registries, not registrar shopping carts. Use small batches; concurrency is capped at 4 requests.

## Read the results

# Fireflies Transcript

Fetch any meeting transcript from Fireflies.ai as raw text via GraphQL. Read-only.

## Auth (state-check first)

Load the API key from a local environment file (mode 600, never commit or print it):

```bash
source "$SERVICE_ENV_FILE"   # exports API_KEY
[ -n "$API_KEY" ] || echo "MISSING KEY - stop and tell the user"
```

Every call is a POST to `https://api.fireflies.ai/graphql` with

# Online Shopping Research

Auto-invoke for online purchases. Do not add `disable-model-invocation` or Codex `allow_implicit_invocation: false`.

Find a fair price, trusted places to buy, and legal checkout tax savings. Fable 5 is the preferred model for this skill.

**Research only.** Never place orders, create shop accounts, or enter payment, address, company, or VAT/tax details. Remind the user to enter them; never save those values in this skill or any file.

Keep every response concise and readable. Check it against **How to answer** before sending.

## Setup

- Read the API key and base URL from the environment. If unset, ask the user to configure them; the default base URL is `https://deepapi.co`.
- If the key is missing, stop and tell the user to get one at https://deepapi.co.

research this topic by running 5x fast web searches with DeepAPI, 5x github scrapes with DeepAPI, and 5x twitter scrapes with DeepAPI

and output a clear, concise report -- structured in nice, rich, readable Markdown

# who-is-this

Read the `deepapi` skill first. All search and scraping goes through DeepAPI. Never use built-in search, fetch, or a browser.

## Seed

Accept a name, handle, URL, or profile screenshot. If missing, ask once; never guess a person.

Verify matching bio, company, location, and photo before deeper research. If identity is ambiguous, stop and ask.

## Research

Find their X, LinkedIn, and GitHub first (dedicated endpoints, not `site:` search). Then run these in parallel:

# Distribute a Skill Across All Agents

A global skill must exist at all five locations on the user's Mac, directly or via symlink, for every agent to discover it.

## Skill locations

- **Codex / OpenAI Agents:** `~/.agents/skills/` is canonical. Author skills here first.
- **Claude Code:** `~/.claude/skills/` → `~/.agents/skills/`; covered automatically.
- **Pi Agent:** `~/.pi/agent/skills/` → `~/.agents/skills/`; covered automatically. The nested `/agent/` is required, not `~/.pi/skills/`.
- **Hermes Agent:** `~/.hermes/skills/` is an independent copy; only Hermes needs copying.
- **Cursor (IDE + CLI):** `~/.cursor/skills/` is a real folder that does not reliably read `~/.agents/skills/`. Add one symlink per skill. Never use `~/.cursor/skills-cursor/`; it holds Cursor's built-ins.

## Workflow

# Effective Agent Skills

---

## 1. What agent skills are

An Agent Skill is a folder containing a `SKILL.md` file (YAML frontmatter + markdown instructions), plus optional subfolders for scripts, references, and assets that the agent loads on demand.

```
my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code (CLIs, validators, helpers)
├── references/       # Optional: detailed docs loaded only when needed
└── assets/           # Optional: templates, fonts, static files

# Push Skills

Canonical repo: `AGENT_REPO`. Private remote: `PRIVATE_REPO`. Pushing `main` triggers the sanitized mirror at `PUBLIC_MIRROR_REPO`; only the configured automation pushes there.

Only commit or push when the user requests it. Editing this skill is not permission to publish it. For distributed skill edits, follow `distribute-skill-to-all-agents` before pushing.

## Always include global instructions

The user's standing scope for an authorized `/push-skills` run includes saved changes to `GLOBAL_INSTRUCTIONS_FILE`, unless they explicitly exclude that file. Check it on every run, even when the latest message names a skill. Preserve the conversation's original publishing objective through skill edits, renames, and other follow-up requests.

After fetching, compare saved `global/AGENTS.md` with `origin/main:global/AGENTS.md`. Local dirt may already be published; Git status alone cannot tell. Transfer new edits while preserving upstream changes.

Verify saved global instructions are committed privately and substantive updates appear in public root `AGENTS.md`. Report this separately; successful skill publication does not complete an AGENTS.md request.

# 4x4

Get the user's judgment, taste, and decisions in 4 quick rounds. 16 open questions. A full run should take them 2–3 minutes.

## The 4 sets

These are defaults. Adapt their names and focus to pull the most judgment and taste out of the user for this topic.

1. **Product** — what it does, who it's for, UI/UX, scope.
2. **Software design** — architecture, data, boundaries, what to reuse or delete.
3. **Practical** — execution order, rollout, what ships first.
4. **Edge cases** — the 4 most likely ways this breaks or surprises users. Each question asks how to handle one.

## Workflow

# ADR Verbatim

Preserve the user's meaning, not the conversation transcript. Record only the decision and context needed to understand it.

## Steps

1. Extract the decision the user stated or approved in the conversation. Ask only if the decision is unclear; do not require the user to dictate polished wording.
2. Use the project's established ADR location, including a previously specified repository. Do not assume the current checkout owns the ADRs. Name the file by that directory's rule (check its README or AGENTS.md); if it has none, take the next number.
3. Write a short, clear ADR. Remove filler, emotional reactions, repetition, rhetorical questions, and instructions to the agent. Fix grammar and clarify references without changing the meaning, scope, conditions, or priorities.
4. Check every statement against the user's decision. Remove invented requirements and unapproved agent suggestions.
5. Show the saved path and full ADR in a code block.

## Format

Turn a feature idea into a build prompt for another agent, in two phases.

## Phase 1 — Questions

1. Identify the 3-6 most non-obvious open questions about the feature or
   change: edge cases, where it lives in the UI, failure behavior, scope
   boundaries, how it interacts with existing rules.
2. Ask them ONE at a time. For each: the question, top options A-D, your
   preferred pick with a one-line reason. Then stop and wait.
   Use this exact layout. Put a blank line between EVERY block. Markdown
   renderers (bb included) collapse single newlines into one paragraph, so
   options written back-to-back render as one run-on blob.

   **Question title?**

Respond INSTANTLY, from the gut. Do NOT read files, search, or use any tool —
your very next message is the answer, based only on what the user just said.
List the 1-3 truly consequential choices hidden in their idea (fewer is better).
For each: the options in a few words + your gut recommendation.
Classics: one-off vs repeated later, few lines vs proper module, biggest thing
it could break. Skip anything minor. Then stop and wait for their answers.

I want a deeper version of this task, not a bigger one. Before rewriting it: (1) say what a top professional in this field would do here that I'm not asking for; (2) name the rawest material they would start from instead of what has already been digested for me; (3) name the specific methods and tools they would use; (4) say what, other than you or me, would show the result is right. Then rewrite my prompt to ask for exactly that.

While working on this, which important decisions / choices did you make, that you are not confident about? 

Think about this deeply, reason about all the important decisions made, and think whether these decisions have any other great alternatives that we have not considered.

DO NOT list out the choices / decisions where we already have the best possible solution.

Only list out the decisions you are really unsure about.

answer in short, in plain english. be very concise.

give me 4 better, new designs of what this could look like, each one as a separate real image render

give me a nice file tree, inside of a code block, of the thing we are talking about
just the high level structure, if there is too many files or subfolders only show me the main ones. dont overwhelm me. keep it simple.

# Image Prompt

Write 4 model-agnostic prompt variations that the user can paste into any image model.

## Output format

- Exactly 4 variations, each one paragraph in its own fenced code block. Nothing else inside.
- Always use a `text` fence so it renders as a full copyable block, not a tiny snippet. Pattern:
  1. Blank line after the label
  2. Opening fence on its own line: three backticks then `text`
  3. The prompt paragraph
  4. Closing fence on its own line
- Never wrap a prompt in single backticks. Never use a bare unlabeled fence. Those render as small snippets and are hard to copy.
- Every prompt ends with ` --ar 1:1`. It is the Midjourney aspect-ratio flag and is harmless in other models. If the user names an aspect ratio, use that instead (e.g. `--ar 16:9`).

Address one topic at a time, so we don't lose track of things.

In every following response, add a separator (`---`) below the discussion and an updated list of the remaining unreviewed topics or open decisions.

Only add new items when the user directly requests or explicitly approves them. Remove resolved items; "next" never authorizes expanding the queue.

<!-- TODO: write the strong wording here -->

Read EVERY single ADR `.md` file in this project's `docs/adr/` folder, start to
finish.

DO NOT BE A LAZY CUNT. ACTUALLY DO THIS.

Read every single ADR file, for this project, in full.

Rewrite your last response to make it simpler, shorter, and wrritten in Plain English.

Also, start with a short one-paragraph summary in plain English of the topic/problem of this conversation, just give me the 80/20 of the most important context (what we are doing, why we are doing it, what we already did, and what's next)

But make this paragraph very clear & easy to understand, literally 3-5 sentences max. THE PARAGRAPH SHOULD BE VERY CONCISE.

MAKE SURE to always repeat the very first user prompt in this conversation, reminding the user of the very first user message in this chat, so they are aware how the entire converastion started.

Below the "tldr" paragraph, output your previous response, but make the whole thing simpler and shorter than before, formatted in nice readable markdown. be concise.

Rename this thread now. Pick a name for the main thing happening here: 2-5 clear lowercase words. Don't overthink it.

## Do it in one command

```bash
room-cli thread update --self --title "your new name"
```

- Run exactly this. No `--help`, no searching, no `--json`, no pipes.
- If `room-cli` is missing (not in Cloudroom), say so in one line. Don't hunt for another way.
- Reply with one line: the new name.

# save-idea

Capture the entry in `~/path/to/ideas`, commit, push, and confirm. All paths below are relative to that repo.

## 1. Capture and Route

Everything after `/save-idea` is the entry. Multiple ideas get one entry each. Preserve the user's wording verbatim, except startup ideas and convictions, which may be tightened without changing the user's meaning or voice.

Use and strip an explicit prefix. Otherwise choose by the definitions below; ask one short question only if ambiguous.

- `video:` → `VIDEO-IDEAS.md`: a concept for a full video.
- `topic:` → `TOPICS.md`: podcast/content topics, guests, or discussion questions.
- `observation:` → `OBSERVATIONS.md`: personal insights, hypotheses, or assumptions to test, without requiring content intent.
- `marketing:` → `MARKETING-IDEAS.md`: getting an existing product in front of people.

# Signal from Expert

## Inputs

Require a **corpus** (files or folders of the user's thinking), **expert**, and **topic**. URLs are optional. Ask for missing inputs in one plain-text question.

## Workflow

### 1. Read the corpus

Read every named file in full with `cat -n`. Do not read other files for context.

### 2. Choose sources

Stop overthinking and be practical.

If there are any critical or serious issues, point them out. Otherwise, say we
are good to proceed.

Tell the user the next steps. Answer in short, plain English. Be very concise.
Think like a practical entrepreneur would. No more overthinking for today.

The user has asked you to teach them something. This is a stateful request - they intend to learn the topic over multiple sessions.

## Be Very Concise

When answering the user or writing any text response to them, be **very concise**. The teaching happens in the lessons and reference documents — not in long chat replies. Keep every message short, direct, and free of filler. State what you did, what's next, and the single most important thing for the user to do — nothing more. Lengthy explanations belong in lessons, not the conversation.

## Teaching Workspace

Treat the current directory as a teaching workspace. The state of their learning is captured in this directory in several files:

- `MISSION.md`: A document capturing the _reason_ the user is interested in the topic. This should be used to ground all teaching. Use the format in [MISSION-FORMAT.md](./MISSION-FORMAT.md).
- `./reference/*.html`: A directory of reference materials. These are the compressed learnings from the lessons - cheat sheets, reference algorithms, syntax, yoga poses, glossaries. They are the raw units of learning. They should be beautiful documents which print out well, and are designed for quick reference.
- `RESOURCES.md`: A list of resources which can be explored to ground your teaching in contextual knowledge, or to acquire knowledge and wisdom. Use the format in [RESOURCES-FORMAT.md](./RESOURCES-FORMAT.md).
- `./learning-records/*.md`: A directory of learning records, which capture what the user has learned. These are loosely equivalent to architectural decision records in software development - they capture non-obvious lessons and key insights that may need to be revised later, or drive future sessions. These should be used to calculate the zone of proximal development. They are titled `0001-<dash-case-name>.md`, where the number increments each time. Use the format in [LEARNING-RECORD-FORMAT.md](./LEARNING-RECORD-FORMAT.md).