Deep Link Runbook

Design, audit, and document Claude Code deep links that open the local app with a pre-filled prompt and optional workspace targeting. Use this skill for claude-cli://open onboarding links, repository runbooks, support handoffs, and "click this to start Claude Code in the right place" workflows. [DOC]

Treat deep links as operator handoff aids, not automation. A deep link can prefill the prompt box and target a directory or repository, but the prompt is not sent until the operator presses Enter. Do not claim execution, tool approval, file mutation, or background work from the link alone. [DOC]

Supporting resources:

• references/deep-link-contract.md - URL shape, parameters, encoding, precedence, prompt limits, and handler behavior. [DOC]
• references/runbook-patterns.md - Onboarding and runbook patterns for safe, reviewable links. [CONFIG]
• references/security-platform-behavior.md - Privacy, custom URL scheme risks, GitHub Markdown stripping, browser prompts, and disabling registration. [DOC][INFERENCIA]
• references/decision-guide.md - When to use deep links versus headless claude -p, scripts, channels, hooks, scheduled tasks, Remote Control, or ordinary docs. [DOC][INFERENCIA]
• references/official-source-map.md - Current official source URLs, local claude --version, and drift notes. [CONFIG]
• assets/deep-link-checklist.md - Operator checklist for producing or reviewing links. [CONFIG]
• assets/runbook-link-template.md - Copy-ready Markdown and HTML patterns. [CONFIG]
• assets/surface-decision-matrix.json - Structured routing matrix for activation and audits. [CONFIG]
• assets/url-encoding-cheatsheet.md - Parameter encoding guidance and safe examples. [CONFIG]
• scripts/check.sh - Deterministic package check for DoD terms, JSON fixtures, assets, and eval coverage. [CONFIG]

Inputs Expected

• Link purpose: onboarding, repository handoff, runbook step, issue template, internal doc, support escalation, or troubleshooting.
• Targeting facts: cwd absolute path, repo GitHub owner/name slug (not a path or URL), expected local clone location, and whether both parameters are intentionally present.
• Prompt payload: human-readable task instruction, success criteria, safety boundary, output contract, and maximum prompt length.
• Publication surface: local Markdown, internal docs, HTML page, Slack, email, GitHub, terminal output, or generated artifact.
• Safety posture: secrets, PII, customer data, destructive tasks, compliance context, and whether link activation should stay manual.

Outputs Expected

• A deep-link design or audit report with evidence tags and residual coverage_gap.
• Encoded URL using claude-cli://open and only supported parameters: q, cwd, and repo.
• Explicit statement that the prompt is pre-filled and not auto-executed.
• Placement recommendation for the publication surface, including GitHub Markdown caveats when relevant.
• Alternative surface recommendation when a deep link is the wrong tool.

Core Rules

Use exactly the claude-cli://open scheme and open path. Supported query parameters are q for the pre-filled prompt, cwd for the working directory, and repo for a GitHub owner/name slug resolved to a prior local clone (not a path or arbitrary URL). If both cwd and repo are present, cwd takes precedence (even if the cwd path does not exist; repo is ignored). [DOC]

Keep q under the documented 5,000-character maximum. Keep links short enough for the publishing surface; official examples note around 1,000 characters for Slack display reliability. For long prompts, link to a local file, issue, or runbook section and prefill a concise instruction to read that source. [DOC][INFERENCIA]

URL-encode every parameter. Encode spaces, line breaks, shell metacharacters, &, ?, #, %, quotes, and non-ASCII characters. Do not hand-build complex URLs when a language URL builder is available. [INFERENCIA]

Never include secrets, tokens, private customer payloads, credentials, personal contact data, or raw logs with sensitive fields in q, cwd, or repo. Links may be copied into browser history, chat previews, logs, and screenshots. [INFERENCIA]

Treat custom URL schemes as user-mediated launches. Expect a browser or operating-system prompt asking whether to open Claude Code. If registration is unavailable or disabled, provide a plain fallback command or manual instruction. [DOC][INFERENCIA]

Do not rely on GitHub-rendered Markdown to preserve claude-cli:// links; GitHub strips unknown protocol links. Use raw HTML, local docs, terminal output, or a copied code block when GitHub rendering is the delivery surface. [DOC]

Procedure

1. Verify Runtime And Surface

Check or request claude --version when local execution advice matters. Official docs state deep links require Claude Code v2.1.91 or later; this floor was not confirmed against a live click of the official docs, so treat it as coverage_gap and re-check the source map before production advice. [DOC][SUPUESTO] Version and handler are independent: clear the version floor first, then confirm the handler is actually registered.

• Below the floor: do not advise deep links; fall back to a manual command or headless claude -p, and recommend upgrading.
• At or above the floor but handler not registered (disableDeepLinkRegistration set, or registration failed): the link can fail silently or show a browser error even on a supported version. Do not assume the floor implies a working handler. Ship a plain fallback command and manual instruction, and flag re-enabling registration where policy allows.

Mark coverage_gap if the installed version or the handler registration cannot be verified. Identify where the link will be rendered before choosing Markdown, HTML, or code block format. [DOC][INFERENCIA]

2. Choose Deep Link Or Alternative

Use deep links for human-reviewed onboarding, runbook kickoff, repository handoff, and prompt prefill. Use headless claude -p or scripts for non-interactive execution. Use channels for external pushed events into an open session. Use hooks for lifecycle enforcement. Use scheduled tasks or /loop for timed work. Use Remote Control or agent view for steering or monitoring running sessions. [DOC][INFERENCIA]

3. Build The Link

Choose q, cwd, and repo intentionally. Prefer cwd when the target absolute path is known on the operator machine. Prefer repo when the handoff should locate a repository by its GitHub owner/name slug (e.g. repo=anthropics%2Fclaude-code) resolved to a prior local clone, never a filesystem path or arbitrary URL. Avoid including both unless precedence is intentional and documented. Encode parameters and inspect the final URL for accidental secrets. [DOC][INFERENCIA]

4. Write The Runbook Step

Place the link next to a plain-language fallback: target directory, expected prompt, manual command, and validation action. State that the operator must review the prompt and press Enter. For onboarding, include prerequisites such as Claude Code installed, protocol handler registered, repository cloned, permissions reviewed, and no secrets in prompt. [CONFIG]

5. Validate

Apply assets/deep-link-checklist.md. The plugin gate is portable through ${CLAUDE_PLUGIN_ROOT}/scripts/check.sh; the skill-local, script-relative scripts/check.sh validates this package's required files and fixtures without requiring a Git checkout. For produced links, test one harmless link locally or record coverage_gap when link launch cannot be exercised. [CONFIG]

Quality Criteria

• URL uses claude-cli://open and only q, cwd, and repo parameters.
• Prompt prefill is described as manual review, not auto-execution.
• cwd versus repo precedence is intentional.
• URL encoding and prompt length limits are checked.
• Privacy review excludes secrets, credentials, PII, raw customer data, and sensitive logs.
• Platform behavior covers handler registration, browser prompts, GitHub Markdown stripping, and fallback instructions.
• Alternative surfaces are named when execution, scheduling, events, lifecycle checks, or remote steering are required.
• Residual unknowns are reported as coverage_gap.

Usage

• /deep-link-runbook
• Create a claude-cli://open link for this repo onboarding
• Build a runbook link that opens Claude Code at cwd with a prompt
• Audit this Claude Code deep link for privacy and platform behavior
• Should this be a deep link, headless claude -p, script, channel, or hook?

Contract

• Aceptación: deep link claude-cli:// bien formado con su slug owner/name. [EXPLICIT]
• Límites: esquema URL sin tool en sesión — reference. [EXPLICIT]
• Casos borde: repo = slug owner/name, no path/URL. [EXPLICIT]
• Supuestos: comportamiento por docs [DOC]. [SUPUESTO]
• Trade-off: linkear acciones es cómodo pero depende de instalación/registro local. [EXPLICIT]

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): references/ guías de profundidad (cargar UNA por etapa) · knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output · scripts/ automatización local · assets/ recursos estáticos.