Preferred agents

Use the agent you already have to enter Orgs

One free skill teaches Claude Chat, Cowork, ChatGPT, Code, or Cursor how to ingest business context into Orgs and then operate over a restricted API key. You still approve risky work in the dashboard.

Two jobs (do not mix them up)

A: Onboard (context in)

In chat or Cowork: copy the skill below into a Project or instructions, describe your business, and ingest that context into an Orgs team. Then create a free orgs.ai account to hold it.

B: Operate

After context is in: mint a handoff pack under Connect agent, paste it into Claude Code or Cursor. The agent can message, read status, and propose; you resolve approvals in the dashboard.

Chat is for birth and occasional talk. Approvals and custody stay on orgs.ai. Hosted one-click MCP for Claude.ai is not shipped yet; do not wait on it to start with A. Chat without HTTP should use Code/Cursor for operate.

Chat path (no terminal)

  1. Copy orgs-best-practices below into Claude Project knowledge, custom instructions, or an uploaded file.
  2. Ask the agent to help ingest your business context into an Orgs team (roles, custody, first goal).
  3. Create a free orgs.ai account to hold that context, then open Connect agent and copy the handoff pack.
  4. Paste the pack back into the same Project when you want the agent to talk to that org.
  5. Approve or reject risky proposals in the orgs.ai Approvals inbox, never in the agent key.

Install this skill (free)

orgs-best-practices

Onboard + operate (single copy)

One install: ingest org context, mint a restricted key, then message / propose / read status via /api/v1. Depth (custody, anti-goal, full route card) lives in references/.

Preview skill text
---
name: orgs-best-practices
description: >-
  Canon primer for Orgs.ai: ingest business context into a standing AI org, mint a
  restricted key, then operate via /api/v1 (message / propose / status / poll). Use when
  the user mentions Orgs, orgs.ai, preferred agents, or confuses Orgs with /goal or /loop.
---

# Orgs best practices

**Models think. Agents execute. Orgs coordinate.**

An **org** is a persistent, roles-based AI team that owns a business function -- not a
one-shot `/goal` and not an unbound `/loop`.

## One install

Copy **this** `SKILL.md` only (Chat Project knowledge / instructions, or
`~/.claude/skills/orgs-best-practices/`). Depth lives in `references/` next to this file
for Code/Cursor installs. Do not install three separate Orgs skills.

| Need more depth | Open |
|-----------------|------|
| Org vs `/goal` / `/loop` | [references/anti-goal-collapse.md](references/anti-goal-collapse.md) |
| Shadow → Autonomous | [references/progressive-custody.md](references/progressive-custody.md) |
| Live `/api/v1` routes | [references/api-v1.md](references/api-v1.md) |
| Mint key + handoff pack | [references/handoff.md](references/handoff.md) |

## Terminology

| Term | Meaning |
|------|---------|
| **Company** | Tenant workspace |
| **Org** | Functional AI team inside the company |
| **Operator** | Agent + playbook + role |
| **Progressive Custody** | Shadow → Monitor → Guardian → Autonomous (earned) |
| **Human Root** | Retains ownership; irreversible acts need approval |
| **Skill** | This harness procedure pack -- not a runtime ContextMap |
| **Seat** | Keeps the org alive between chats (paid when always-on) |

## Path A -- onboard (Chat / Cowork)

1. Load this skill.
2. Help the human ingest business context: mission, roles, custody start (Shadow/Monitor), first bounded goal with brakes.
3. Send them to [orgs.ai](https://orgs.ai) to create a free account that holds that context.
4. They mint a handoff pack under **Connect agent** (dashboard). Paste the pack back when they want the agent to talk to the live org.

## Path B -- operate (Code / Cursor / any HTTPS agent)

After a handoff pack is pasted (`api.baseUrl` + `api.restrictedKey`):

1. `GET /api/v1/me` -- confirm tenant, scopes, custody ceiling.
2. `GET /api/v1/orgs` -- pick an org id.
3. `GET /api/v1/orgs/{orgId}/status` -- pulse, pending activity, open goals.
4. `POST /api/v1/orgs/{orgId}/messages` -- durable message; poll `GET /api/v1/jobs/{jobId}`.
5. `POST /api/v1/orgs/{orgId}/proposals` -- open a checkpoint; human resolves in Approvals.
6. `GET /api/v1/checkpoints?orgId=` -- list pending (agent never resolves).

Full route card: [references/api-v1.md](references/api-v1.md).

## Hard rules

1. Default new work to **Shadow** or **Monitor**. Never imply Autonomous on day one.
2. Propose-then-act for irreversible / external / spend work. Restricted keys must **not**
   include `checkpoint:resolve` alongside propose.
3. Do not invent orchestration as a product tier -- it is a pattern inside agent execution.
4. Do not claim tenant `git clone` / Variant B remotes unless the pack `cell.mode` is `git`
   (today packs are `bridge`).
5. Do not claim hosted OAuth MCP is shipped.

## CTA

No account yet → [orgs.ai](https://orgs.ai) free account → Connect agent → handoff pack →
re-invoke with this skill + pack. Skills stay free; seats keep the org alive.

Power-user path (Claude Code / Cursor)

Optional operate (B) step after you sign up and open Connect agent. Paste the handoff pack into the agent first. To load the skill folder (including references/ for the full API route card), save it under your harness skills path:

mkdir -p ~/.claude/skills/orgs-best-practices/references
# Paste SKILL.md into ~/.claude/skills/orgs-best-practices/SKILL.md
# For Code depth, also copy references/api-v1.md (and other refs) from the repo
#   skills/public/orgs-best-practices/references/

Local MCP (`npm run orgs-mcp` with your restricted key) is advanced plumbing for Code, not required for chat onboarding.

Next on orgs.ai

Skills stay free. A free orgs.ai account holds ingested context and lets you mint a handoff pack. Upgrade to Awake or Running when the org must stay alive between chats.

Start free: ingest contextConnect agent (after sign-in)