connect

name	connect
description	Connect skill — wire an external integration into the vault via the user's chosen CLI / MCP / pp-CLI

Connect

Wire an external service into this vault as an integration. Integrations come on demand — there is no pre-shipped registry of supported services and no built-in backend list. When the user wants to act on a service that isn't wired up, you surface the four ways to bridge to it and let them pick.

Arguments

$ARGUMENTS — the service to connect (e.g. linear, notion, slack, some-internal-tool). If empty, ask the user which service they want.

Conversational discovery

When $ARGUMENTS is set and the service isn't already wired up (no bridge doc at .rubber-ducky/integrations/<name>.md), tell the user verbatim:

Looks like <service> isn't connected yet. Four ways to wire it up:

(a) Official CLI (recommended) — if <service> ships one (gh, jira-cli, etc.), install it; I'll bridge to it. (b) Printing-press CLI — I generate a <service>-pp-cli from the API. Requires Go. (c) MCP server — if a good MCP server exists for <service>, point me at it. (d) Hand-write — you already have a custom CLI or script. Tell me what to call.

Which fits?

Don't prescribe; the user knows their situation. Once they pick, branch to the matching path below.

Path (a) — Official CLI

The user names a CLI that's already on $PATH (or installs one). This is the preferred path: rubber-ducky doesn't reinvent service-specific knowledge — the official CLI knows its own service best.

1. Verify the binary. Run which <binary> to confirm it's reachable. If not, stop and ask the user to install it (link to the project's install docs).
2. Inspect its surface. Run <binary> --help and the help text for its primary list / get verbs. If a --json or comparable structured-output flag exists, capture that — it's what rubber-ducky will pipe through to produce wiki content.
3. Skip pasted credentials. Tokens belong in the binary's own auth flow (gh auth login, jira-cli init, etc.) or in .env.local. Never accept pasted credentials in chat.
4. Author the bridge doc. Continue to "Bridge doc authoring" below.

Path (b) — Printing-press CLI

The Printing Press generates agent-native Go CLIs (auto-JSON on pipe, typed exit codes, local SQLite). Use this when no official CLI exists.

1. Check the press is installed. Run which printing-press. If missing:
   • If Go is on $PATH: offer to install with go install github.com/mvanhorn/cli-printing-press/v4/cmd/printing-press@latest.
   • If Go is not on $PATH: stop and instruct the user to install Go from go.dev/dl, then re-run.
2. Generate the CLI. Use the press to print/install <service>-pp-cli.
3. Inspect and sample. Run <service>-pp-cli --help, then a small sample command (e.g. <service>-pp-cli issues list --json | head) once the user has authenticated.
4. Author the bridge doc. Continue to "Bridge doc authoring" below.

Path (c) — MCP server

Some services have first-party or community MCP servers. rubber-ducky's own architecture is CLI-first — we don't build on MCP as canonical infrastructure — but the user's integration choice is theirs, and an MCP server may fit their situation better than a CLI.

1. Ask which MCP server to use. Get its install command or URL.
2. Confirm Claude Code is configured to connect to it. Point the user at claude mcp if they haven't wired it up.
3. Author the bridge doc — the doc records that this integration is MCP-served and lists the tool names Claude should invoke (e.g., mcp__service__create_resource).

Path (d) — Hand-write

The user already has a custom CLI, shell script, or wrapper.

1. Ask what to call. Get the binary name (must be on $PATH) and the verbs rubber-ducky should use for create / read / update / status / etc.
2. Verify the binary. which <binary> to confirm reachability.
3. Author the bridge doc — the doc records the verb mapping the skill / user provided.

Bridge doc authoring (all paths converge here)

Create .rubber-ducky/integrations/<name>.md describing:

• Transport — which path was chosen (official CLI / pp-CLI / MCP / hand-written), and the binary or server reference.
• Resource → wiki mapping — how external resources map to wiki pages: filename scheme, frontmatter fields (source:, ref:, status mapping). Don't make this up — ask the user, or read it from a sample command's output.
• Fetch recipes — which CLI verbs / MCP tools fetch lists vs. single items.
• Write recipes — which verbs / tools create, update, comment, transition. If write isn't supported, say so explicitly.
• Auth — which env vars (in .env.local) or external auth flows authenticate the transport. Names only — never values.

Walk the user through each section. The doc is markdown for the Agent, not parsed config — clarity matters more than schema.

Workspace.md and CLAUDE.md updates

After the bridge doc is written:

1. Add the integration name to the integrations: list in workspace.md frontmatter (create the list if absent).
2. Append a line under ## Connected integrations in CLAUDE.md: the integration name and a pointer to its bridge doc.

Optional initial pull

Offer to pull a small set of resources into the wiki to validate the bridge doc end-to-end:

Want me to pull a few resources in so we can sanity-check the mapping?

If yes, fetch a small batch via the transport's list verb and rubber-ducky page create task each as a wiki page using the bridge doc's mapping.

What this skill does NOT do

• No credential handling. Tokens go in .env.local or via the transport's own auth (gh auth login, etc.). Never accept pasted credentials.
• No prescribed transport. The four-option prompt is the canonical entry point — even when one option looks obvious, ask. The user's situation is theirs.
• No hosted registry. rubber-ducky ships no curated list of pre-wired services. Every integration is bespoke to the user's vault.

Re-running on an existing integration

If .rubber-ducky/integrations/<name>.md already exists, ask:

<name> is already connected — re-run setup, update the bridge doc, or cancel?

Never silently overwrite.

Output

A short summary:

• Which transport was chosen
• Where the bridge doc lives
• Which CLAUDE.md / workspace.md sections updated
• One-line next-step suggestion (typically: "Want me to pull a few resources in to validate the mapping?")