Pipecat Context Hub

View saved version →

---
name: build
description: Build and verify a local Pipecat app after an explicit build request, using native local execution, installed CLI capabilities and grounded Context Hub APIs.
---

A build request authorises local project work within the chosen workspace.
An idea/concept discussion alone authorises only exploration. Skills do not
grant execution permissions. This workflow requires native local shell/file
execution and the installed Pipecat CLI; it does not use a shell MCP adapter.
If either is absent, report build unavailable, retain working exploration and
offer [required CLI setup](../setup/SKILL.md#required-workflow-clis). Pipecat CLI
is required for building; PCH query commands do not replace it.
Cloud account access is not required for local build. Deployment is a separate
workflow; hand off to deploy for read-only preparation and a concrete approval
payload. Do not upload secrets, deploy or start remote agent sessions here.

## Gate and resolve choices

1. Confirm this chat has native local execution using a harmless shell command.
   Inspect `pipecat --version` and `pipecat init --help`. If unavailable, explain
   the missing capability without installing/upgrading tools automatically. If
   the version is older than the requested capability requires, hand off to
   [Setup's older-CLI flow](../setup/SKILL.md#handle-an-older-pipecat-cli) and
   present one approval-gated upgrade proposal; do not upgrade merely because a
   newer release exists. Continue with the installed CLI when it supports the
   requested build.
   Use `pipecat init --list-options` only if advertised; parse its JSON and
   retain the actual service identifiers and transport combinations. Installed
   help/options take precedence over newer docs. Never assume `--eval`, inferred
   bot type, config keys or flags that this version does not advertise.
2. Resolve material user choices before generation: selected project directory
   and name, browser versus telephony, transport, cascade versus realtime,
   providers, client requirements, intended behaviour and target framework
   version. Ask focused questions for missing choices; do not invent providers,
   credentials or use a qualification fixture as user defaults. Map choices to
   actual CLI identifiers. Explain unsupported combinations rather than
   silently substituting them. Clarify optional recording/video/observability
   choices when relevant. For a local build, disable Cloud file generation when
   supported; explain if this CLI requires those files anyway.
3. Inspect the selected output directory and the actual project-name child the
   CLI will create, including hidden entries, without reading existing `.env`
   files. Refuse scaffolding into any nonempty destination, existing app or
   symlink to one. Do not delete files to make it empty or force overwrites.
   For an existing project, adapt its current structure and dependency lock
   within the requested scope; do not re-scaffold. A new app needs an explicitly
   selected absent/empty directory. Recheck immediately before generation.

## Dry run, scaffold and ground customization

Build one explicit argument list from supported options. On CLI 1.3.0,
noninteractive mode uses `--name` or `--config`; `--bot-type` is required in
observed probes, and `--client-framework none` means no client. These are dated
compatibility facts, not permanent defaults. If using JSON `--config`, discover
its schema through installed documentation or a valid dry run; do not assume
`--list-options` is a config schema. Inspect resolved JSON, not just exit status.

Run the supported `--dry-run` with the same selections and output path as the
planned scaffold. Verify resolved name, bot type, transports, mode, providers,
client and optional features; ensure no files were created. Resolve errors or
unexpected defaults before proceeding. If this version lacks a safe dry run,
report that gate unavailable instead of silently generating. Then recheck the
empt

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: deploy
description: Prepare a Pipecat Cloud deployment with read-only checks and an exact approval payload, then execute only approved secret changes, build and deployment and verify readiness.
---

A deployment request authorises preparation in the selected app workspace.
Before concrete approval, Cloud inspection is read-only. Do not create/update
secrets, upload source, build images locally or remotely, push to a registry,
deploy, start agent sessions, delete deployments or roll back. `deploy` is not
a dry run. Skills do not grant execution permissions. Exploration and local
build remain available when Cloud prerequisites are missing. Pipecat CLI and
its Cloud extension are required for deployment, separately from PCH query
readiness. Offer [required CLI setup](../setup/SKILL.md#required-workflow-clis)
when they are absent; preparation does not install them silently.

## Discover and prepare

1. Confirm native local shell/file execution, selected existing app and installed
   Pipecat/Cloud CLI versions. Inspect installed help for deploy, secret list/set,
   organisations, regions, profiles, status and logs. Discover actual flags and
   config schema; installed capabilities take precedence over newer docs.
   Missing execution/CLI disables deployment only; never install an adapter or
   upgrade tools silently. Preserve the existing bot, dependency pins and lock;
   never re-scaffold an existing project to obtain Cloud files.
2. Follow [Explore's CLI retrieval](../explore/SKILL.md#cli-retrieval) using the
   installed PCH command. Check status before/after, retrieve relevant docs/API/
   examples and retain
   source citations. Separate multiple concepts with ` + ` or ` & `; inspect
   installed command help before passing filters. Ground Dockerfile
   and runtime entrypoint
   choices, including transport/runner compatibility, in retrieved definitions.
   Version annotations do not switch indexed snapshots. Missing/unknown evidence
   stays unresolved; never refresh/reset/repair or change the index/version pin.
3. Validate the selected path's supported runtime, entrypoint and deploy
   configuration. For source builds, also validate project layout, asynchronous
   bot entrypoint, dependency lock and Dockerfile. For source builds, verify
   required build tools against the exact pinned base, not a mutable tag or newer
   template.
   If absent, supply an explicit immutable tool input (for example, digest-pinned
   official uv binaries with the required platform and lock-format support).
   For source builds relying on the inherited entrypoint, inspect that base's
   config and revision-linked entrypoint source to establish its Python, PATH,
   workdir and dependency environment. Install into the Python
   environment the inherited entrypoint actually uses; default uv `.venv` creation
   is insufficient when that entrypoint runs system Python. Preserve base server
   dependencies (for example, an explicitly targeted `uv sync --inexact`, with
   conflicts and required imports checked) and inherited CMD. For source builds
   deliberately selecting a custom entrypoint, validate it against its own
   runtime and dependency environment. Preserve project/lock bytes for all source
   builds. Existing immutable registry images require verified image digest,
   platform and relevant runtime evidence, without a rebuild, dependency
   installation or unavailable base-source provenance.
   Manifests/source inspection proves inputs, not a successful build or runtime.
   Prepare only needed
   local files, preserving existing ones. Inspect required key **names** from
   placeholders/source without reading existing `.env` contents or printing
   values. Distinguish required provider keys from optional settings/defaults
   and Cloud management authentication. A local `.env` is not automatically
   transferred to Cloud. Do not copy it into an image or build context.
4. Check authentication through read-only organisation metadata. Nev

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: explore
description: Explore a voice or multimodal agent idea or Pipecat concept, including STT/LLM/TTS pipelines and real-time speech-to-speech patterns supported by Pipecat, using sourced documentation, API definitions and examples.
---

Use the installed PCH query CLI through native command execution. Prefer
`pipecat context-hub` when installed help exposes its PCH commands; otherwise
use standalone `pipecat-context-hub`. This skills-only plugin does not require
an MCP connection. Native execution, a compatible runtime and a populated
Context Hub index are required for grounded retrieval. If they are absent,
report retrieval unavailable and offer [Context Hub setup](../setup/SKILL.md).
Cloud credentials are not required for exploration.

Exploration is read-only. An idea or concept question authorises retrieval and
discussion, not dependency installation, indexing, scaffolding, persistent local file writes
(semantic retrieval may use a temporary private Chroma snapshot),
execution of examples, builds, secret access/uploads or deployment.
After an explicit build request, hand off to the build skill to check native
execution, installed CLI and material project choices. After a deployment
request, hand off to deploy for read-only preparation and concrete approval
before secret writes, image builds or Cloud mutations. Skills do not grant
executable permissions.

## Readiness and preferences

1. Resolve the configured index directory without creating it: honour
   `PIPECAT_HUB_DATA_DIR` when set, otherwise use `~/.pipecat-context-hub`.
   Inspect only path existence and file types. If the directory or either
   required database (`chroma/chroma.sqlite3` and `metadata.db`) is absent, do
   not run `status`: report retrieval unavailable and offer Setup. Never create
   directories or placeholder files during this preflight. When the artifacts
   exist, run CLI `status` before retrieval. Record the selected executable/prefix,
   record count, refresh date, `framework_version` (operator pin),
   `indexed_framework_version` (observed release) and
   `indexed_framework_commits_ahead` when present. Also record
   `catalog_groups_not_indexed` as a coverage boundary. Treat
   `indexed_repos` and `configured_no_records` as local machine metadata: use
   them to explain coverage to the user, but never copy them into a public
   issue because they may contain private repository names. A `latest` pin is
   not proof of today's latest release. Retain relevant commit citations.
2. Check exit codes and parse stdout as JSON, keeping stderr diagnostics separate.
   Missing execution/runtime/index means retrieval unavailable; offer Setup and
   wait for an explicit request before installation or initial indexing. Index
   failures, invalid input, low confidence, empty hits and unavailable versions
   are not reasons to select another index or silently switch installations.
   Explain startup remediation without running it. An empty index cannot ground
   an answer. A stale index can supply explicitly dated evidence with a coverage
   limitation. Unknown provenance is not a freshness pass. A query may carry a
   top-level `corpus_hint`; report its matched group and missing/configured
   repositories before using the results, and offer its `add_command` or
   `refresh_command` for the user to run later. Never execute those commands,
   refresh/reset/repair during exploration, or treat a missing hint as proof of
   complete coverage. Exit 75 means a refresh is in progress; explain that the
   user can retry after it finishes rather than selecting another index.
   Describe reranker limitations from status; `config_disabled` is an operator
   choice, not a bug.
3. Extract the user's idea/concept, Pipecat version and source preference.
   Inspect installed CLI help before mapping preferences:
   installed command versions may differ from this source package. Use only supported
   arguments.
   If a preference cannot be enforced, say so before

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: setup
description: Set up the Pipecat Context Hub plugin after an explicit request, checking native CLI retrieval and required Pipecat/Cloud tools, installing missing prerequisites, creating an initial index and guiding Cloud account signup and login when authorised.
---

Use this workflow when the user requests plugin, Context Hub or Pipecat/Cloud
CLI setup. Determine the requested capabilities from the conversation: full
plugin setup includes the build/deploy toolchain; explicitly retrieval-only
setup needs only PCH. PCH CLI supplies retrieval; Pipecat CLI and its
Cloud extension are required tools for Build and Deploy respectively.
Plugin installation or an exploration question alone does not authorise
dependency installation or index creation. The plugin contains skills and assets,
not Python, command-line
tools or an index. Its setup runs in the selected execution environment; it does
not configure a desktop MCP client or deploy a remote MCP service.
Skills supply instructions, not execution permissions or installation hooks.

## Inspect and propose setup

1. Identify the execution environment and selected client. Check native shell/file
   access with a harmless command. A local computer or cloud execution environment
   can run PCH when it supports Python and subprocesses; installing a plugin on
   the web does not provision that environment. Record whether its runtime/index
   will persist between tasks. Cloud container paths, indexes and login do not
   configure or authenticate another execution host.
   Before any index operation, require a POSIX host with descriptor-relative,
   no-reparse filesystem support. Windows is package/path smoke only: do not
   run `refresh`, `serve`, or semantic queries against a populated index there;
   these operations must fail closed rather than falling back to pathname-based
   deletion or opening.
   If native execution is unavailable, report setup and grounded retrieval
   unavailable and provide the user's remaining setup steps; do not install an adapter.
2. Batch the bounded read-only preflight before proposing any mutation. In one
   pass, inspect native execution, the selected PCH command/status, `pipecat
   --version`, `pipecat init --help` and, for Cloud, the required read-only help
   and organisation metadata. Do not ask for approval for these reads and do not
   split them into separate approval prompts. Report all findings together.
   Discover PCH through [Explore's CLI retrieval](../explore/SKILL.md#cli-retrieval):
   verify `pipecat context-hub` or standalone `pipecat-context-hub`, installed
   help and JSON `status`. Inspect failures before choosing a path: exit 2 alone
   does not prove an empty index. Record versions, index path, count, refresh
   date, framework pin, indexed framework version and any
   `catalog_groups_not_indexed` coverage gaps. Treat `indexed_repos` and
   `configured_no_records` as local metadata that may contain private names;
   reuse the selected installation/index rather than silently picking another.
   Separately inspect `pipecat --version`, `pipecat init --help` and, for Cloud,
   `pipecat cloud --help`, `pipecat cloud auth login --help` and organisation-list
   help. A listed `cloud` command may be an unavailable-extension stub; require
   working subcommand help rather than treating the root listing as readiness.
3. Reuse working PCH and a healthy populated index. Staleness, a different requested
   framework version or disabled reranking does not authorise refresh, upgrade or
   model downloads. A corrupt/unreadable existing index is a separate recovery
   request; stop that branch without reset, repair, deletion or a replacement index.
4. Present the concrete changes needed: required PCH/Pipecat/Cloud package/version
   specifications and retained extensions, tool-manager
   environment, resolved initial-index path and sources/framework pin, required
   storage/persistence and any existing-file backup.
   Explain that firs

Preview of the first 4,000 characters. Read full instructions →