aai-labs/agent-barn

# aai-cli Apollo

Use this skill when working with Apollo through `aai-cli apollo`.

Before running commands, confirm the active profile or pass `--profile`. Apollo profiles use API-key auth (`auth_type = "apollo_api_key"`) with `api_token_secret`.

Apollo keeps discovery records and saved records separate. Use `people` and `organizations` commands for sourcing and enrichment; use `contacts`, `accounts`, and `deals` commands for saved Apollo CRM/workflow records.

For Sally-style sales workflows, treat Apollo as the source for sourcing, enrichment, sequence membership, and Apollo-run outreach activity. Do not treat Apollo as the final CRM unless the task explicitly says so. If respondents are handed into Pipedrive manually, call that out clearly.

Successful output is JSON on stdout. Errors are structured JSON on stderr. See [the command reference](references/command-reference.md) for command shapes, response notes, and real example output captured from a live Apollo account.

# aai-cli Bitbucket

Use this skill when working with Bitbucket Cloud through `aai-cli bitbucket`.

Before running commands, confirm the active profile or pass `--profile`. Repository-scoped commands accept `--repo`; newer repository commands also accept `--owner` plus `--repo`. `repos list` is workspace-scoped and accepts only `--limit` — never pass `--owner` to it. A `workspace/repo` value overrides the configured workspace.

For pull request review work, start with `prs get`, inspect changed files with `prs diffstat`, fetch large diffs with `prs diff --output`, and read exact file contents with `source get <commit> <path>` before commenting.

Successful output is JSON on stdout. Errors are structured JSON on stderr. See [the command reference](references/command-reference.md) for command shapes, response notes, and review workflows.

# aai-cli Confluence

Use this skill when working with Confluence Cloud through `aai-cli confluence`.

Before running commands, confirm the active profile or pass `--profile`. Prefer typed commands for spaces, pages, comments, attachments, and page moves; use `confluence request` only for uncommon Confluence REST endpoints.

List commands aggregate pagination up to `--limit` and return trimmed provider envelopes. Get commands return full raw provider responses.

Successful output is JSON on stdout. Errors are structured JSON on stderr. See [the command reference](references/command-reference.md) for command shapes, response notes, and examples.

# aai-cli Excel

Use this skill when working with spreadsheet files on disk through `aai-cli excel`.

Read and write `.xlsx`, `.xlsm`, `.csv`, `.tsv`. Read-only: `.xls` (Excel 97–2003), `.xlsb`, `.ods` — to edit one, save it as `.xlsx` or `.csv` first.

These are local files. There is no account, profile, or credential involved — do **not** pass `--profile`, and do not ask the user to authenticate. Just point the command at a file path.

Use `workbook create` to start a new file, `sheets list` to discover tab names and how far each one's data extends, `sheets add`/`delete`/`rename` to change the tabs of an existing `.xlsx`, then `values` commands to read, update, or clear ranges.

Ranges use A1 notation and accept the same forms as Google Sheets: `'Sheet1'!A1:D5`, a single cell, an open column range (`B:C`), an open row range (`2:5`), or a bare sheet name for everything in use. `values update` expects `--values` as a JSON array of row arrays, and writes starting at the range's top-left cell.

A `.csv`/`.tsv` file is a single sheet named after the file (`sales.csv` → `sales`), so `--sheets` does not apply when creating one and the `sheets add`/`delete`/`rename` commands do not either.

# aai-cli GitHub

Use this skill when working with GitHub through `aai-cli github`.

Before running commands, confirm the active profile or pass `--profile`. GitHub profiles normally provide `owner` and `repo`; most commands also accept `--owner` and `--repo` overrides.

For pull request review work, start with `prs get`, inspect changed files with `prs files`, fetch large diffs with `prs diff --output`, and read exact file contents with `source get <sha> <path>` before posting comments or reviews.

Successful output is JSON on stdout. Errors are structured JSON on stderr. See [the command reference](references/command-reference.md) for command shapes, response notes, and review workflows.

# aai-cli Gmail

Use this skill when working with Gmail through `aai-cli email` and a Gmail REST profile.

Always pass the intended Gmail profile with `--profile` unless the active default profile is already known. `messages list` returns message stubs; use `messages get <MESSAGE_ID>` to read decoded subject and body content.

Date filters on `messages list` are translated to Gmail search syntax. Send commands accept typed flags or documented JSON payloads.

Successful output is JSON on stdout. Errors are structured JSON on stderr. See [the command reference](references/command-reference.md) for command shapes, profile expectations, response notes, and examples.

# aai-cli Google Drive

Use this skill when working with Google Drive through `aai-cli drive`.

Before running commands, confirm the active profile or pass `--profile`. Drive profiles are ordinary Google REST profiles (`provider = "google"`, `auth_type = "bearer_token"`), the same shape as Gmail, Calendar, and Sheets.

This arm is read-first. `files upload` is the one write: it creates a new Drive file from local bytes. Nothing here changes sharing, renames, moves, trashes, or deletes — and `permissions` is read-only on purpose, so an agent cannot widen who can see a file.

Start from `files list` (or `folders list`) to turn a name into a file ID, then `files get` for full metadata and `files download` for content. `--parent <folder-id>` scopes a listing to one folder; `--drive-id <id>` scopes it to one shared drive. Shared-drive content is included by default.

`files download` writes to `--output` and never prints content to stdout. Google-native documents have no bytes of their own, so they are exported instead: Docs to `.docx`, Sheets to `.xlsx`, Slides to `.pptx`, other native types to PDF. Pass `--mime-type` to choose a different conversion. Exports are capped at 10 MB by Google, and native documents report no `size`, so that cap only shows up as an error.

For cell-level work on a Google Sheet, use the `aai-cli sheets` commands instead of downloading the file.

# aai-cli HubSpot

Use this skill when working with HubSpot through `aai-cli hubspot`.

Before running commands, confirm the active profile or pass `--profile`. HubSpot profiles use `auth_type = "hubspot_service_key"` or `auth_type = "hubspot_legacy_private_app"` with `token_secret`.

HubSpot `401` and `403` errors include scope and auth-model remediation under `details`. Preserve that JSON when reporting failures. Custom channel commands are not supported for legacy private app tokens and return `unsupported_auth` before making a request.

Successful output is JSON on stdout. Errors are structured JSON on stderr. See [the command reference](references/command-reference.md) for command shapes, scopes, and failure handling.

# aai-cli Jira

Use this skill when working with Jira Cloud through `aai-cli jira`.

Before running commands, confirm the active profile or pass `--profile`. Prefer typed commands for common issue, idea, sprint, board, project, comment, and attachment workflows; use `jira request` only for uncommon Jira REST endpoints.

For Jira Product Discovery, use `jira ideas` commands: they scope searches to Product Discovery projects, default the create issue type to `Idea`, and discover project-specific idea fields (`jira ideas fields PROJECT`) so custom fields like Impact or Effort can be set through `--json`.

List commands aggregate Jira pagination up to `--limit` and preserve the documented response shape. Create and update commands accept typed flags and, where documented, `--json` payloads.

Successful output is JSON on stdout. Errors are structured JSON on stderr. See [the command reference](references/command-reference.md) for filters, payload rules, response shapes, and examples.

# aai-cli Merkys

Use this skill when the answer should come from the organization's Merkys knowledge base (uploaded documents, connected Jira/Confluence/Drive/email sources, and the legal or medical corpora) instead of from your own memory or the web.

Before running commands, confirm the active profile or pass `--profile`. A Merkys profile uses a **user API key** sent in the `X-API-Key` header (`auth_type = "api_key_header"`) and needs a `base_url`. Everything you do is done as the key's owner: you only see what that user's role and access rules allow, and your questions appear in that user's conversation history.

## Which command

- `merkys ask "<question>"` — start here. One command creates a conversation, asks, and returns `{answer, sources, conversation_id, ...}`. Takes roughly 5–30 seconds.
- `merkys research start "<question>" --wait` — for broad questions that need several searches and a written report (about 1–5 minutes). It returns the finished run with `final_report`, `sources`, and `plan`. Without `--wait` it returns a `run_id` at once; check it later with `research get <run-id>`. If `--wait` times out the run keeps going: the error includes the `run_id`.
- `merkys conversations list|search|messages`, `documents list`, `sources list`, `assistants list` — look around: what was asked before, what is uploaded or connected.
- `merkys request GET <path>` — anything else read-only (legal corpus, case law, law commentary, medical corpus, statistics). See [the endpoint reference](references/api-endpoints.md).

## Reading an answer

# aai-cli Microsoft Graph

Use this skill for Microsoft 365 work through `aai-cli microsoft`. Start from the user's intent and Microsoft 365 ownership model, not from the command list. Read the concepts reference before a cross-service or file-editing workflow.

## Choose the service first

- **Outlook / Exchange** owns a user's mail, calendar, and contacts. Use it for communication and scheduling tied to a mailbox.
- **OneDrive** is a user's personal work-file area. Use it for files owned or staged by one user, even when those files may later be shared.
- **SharePoint** is the shared content layer. A site contains document libraries (`drive` resources) for files and lists for structured rows/columns. Use document-library file commands for shared documents; use list-item commands for records such as requests, assets, or statuses.
- **Teams** is the collaboration/conversation layer over teams and channels. Read channel messages and membership there, but treat channel files as SharePoint content. A standard channel uses the team's SharePoint site; private and shared channels can use separate sites.
- **Microsoft To Do** is user-centered personal task management. Use it when the task belongs in one user's lists and daily workflow.
- **Planner** is shared plan/task management, commonly attached to a Microsoft 365 group or Team. A plan contains buckets, and buckets organize tasks.
- **Microsoft Graph** is the common API surface across these products. Use `microsoft request` only when the needed Graph operation lacks a typed command.

# aai-cli OpenPanel

Use this skill when working with OpenPanel analytics through `aai-cli openpanel`.

This is a **read-only** integration — there are no write endpoints (no `identify`/`track` calls, no project or client management). Always pass the intended profile with `--profile` unless the active default profile is already known.

OpenPanel clients are typed `write`, `read`, or `root` server-side, and this matters for which commands work with a given profile:
- `projects list` / `projects get` (the Manage API) require a `root` client.
- `events export`, all `insights *` commands, and `profiles *` commands require a `read` or `root` client.
- A project's default `write` client fails every command here with `401`/`403`.

`insights *` and `profiles *` commands need a project ID in the URL — pass `--project-id` or set `profile.project_id` to avoid repeating it. `events export`'s `--project-id` is optional: omit it when the profile's client is already scoped to a single project.

`insights pages`/`referrers`/`devices`/`geo` accept `--limit`/`--cursor` but the provider ignores them — those four always return every breakdown row for the date range, unsorted. To answer a "top N" question, fetch all rows, then sort and slice client-side. Only `events export` really paginates, and a `{ "name": null, ... }` breakdown row is the "no value for this dimension" bucket, not an error.

# aai-cli Pipedrive

Use this skill when working with the Pipedrive CRM through `aai-cli pipedrive`.

Before running commands, confirm the active profile or pass `--profile`. Pipedrive profiles use a personal API token (`auth_type = "pipedrive_personal_token"`); no `owner`/`repo`-style scoping is needed since a profile maps to one Pipedrive account.

For a combined view of a CRM record, prefer `deals view` / `persons view` / `organizations view` over separately calling `get` + `activities` + `notes` — it aggregates all three (plus optional email) in one response. For deal stage-transition history specifically, use `deals flow`, which surfaces `dealChange` entries with `field_key: "stage_id"`.

Meeting transcripts and other documents are usually file attachments, not notes. List them with `files list --deal-id` / `--person-id` / `--org-id` and fetch each with `files download <id> --output PATH`, then convert it to text before reading.

Record payloads refer to custom fields by hash key and to option values (Industry, custom dropdowns) by numeric ID. Resolve them with `fields <deals|persons|organizations> list` before matching records by a field's name or value.

List commands stop at `--limit` (usually 50). When `_aai.pagination.status` is `more_available`, the result is partial — raise `--limit` before counting or summarizing records.

# aai-cli PostHog

Use this skill when working with PostHog product analytics through `aai-cli posthog`.

Before running commands, confirm the active profile or pass `--profile`, `--project-id`, or environment variables `POSTHOG_API_KEY`, `POSTHOG_PROJECT_ID`, and `POSTHOG_HOST`.

PostHog integration is read-first for product decision-making, idea discovery, and release impact correlation. Prefer typed subcommands for discovering projects, saved team insights, cohorts, dashboards, and annotations. For custom analytics, use `posthog events query` with HogQL queries or raw JSON query payloads.

List commands aggregate PostHog pagination up to `--limit` and preserve the provider response shape (`count`, `next`, `previous`, `results`).

Successful output is JSON on stdout. Errors are structured JSON on stderr. See [the command reference](references/command-reference.md) for command shapes, response notes, query examples, and output shapes captured from a PostHog workspace.