---
name: agent-deep-links
description: >
  Constructor y validador de deep links para abrir archivos, líneas, carpetas y
  ajustes directamente en IDEs y editores desde notificaciones, mensajes del
  gateway o output de agentes. Cubre VS Code (vscode://), VS Code Insiders,
  Cursor (cursor://), JetBrains (jetbrains://), Codex Desktop (codex://) y
  fallbacks para apps sin esquema oficial. Cargar cuando un agente o hook deba
  emitir referencias a archivo:línea que el usuario pueda abrir con un clic
  desde Telegram, desktop notifications, Discord, Slack o e-mail.
version: 1.0.0
nivelRiesgo: BAJO
herramientasPermitidas: [Read]
exclusiones:
  - "No invocar para generar URLs HTTP/HTTPS de navegación web — esto es solo para deep links a apps de escritorio."
  - "No invocar para integraciones con servicios externos (Linear, Notion, Jira); este skill solo cubre IDEs y editores locales del desarrollador."
  - "No invocar para enlaces a sesiones de Claude Code en la nube — esos son URLs claude.ai/code/..., no deep links."
---

# /habilidades/agent-deep-links — Deep links a IDEs

## Cuándo cargar

- Antes de emitir una notificación que incluya referencias a archivos del proyecto
  desde `notificador-swl`, `hooks/lib/gateway-notify.js`, `inbox-aviso.js`,
  `notificacion-sesion-stop.js` o cualquier hook que mencione `archivo:línea`.
- Al diseñar nuevos hooks o agentes que produzcan output con referencias a código
  que el usuario pueda querer abrir directamente.
- Antes de generar mensajes desde el `documentador-swl` cuyo destino sea un canal
  externo (Telegram, Discord, e-mail) y el receptor probablemente esté en su
  IDE.

## Cuándo NO cargar

- Cuando la notificación es solo texto plano sin referencias a archivos
  (mensajes de status, métricas agregadas).
- Cuando el receptor es un agente, no un humano (los agentes no abren IDEs).
- Cuando estás generando URLs de navegación web (HTTP/HTTPS) — usa generación
  estándar.
- Cuando el proyecto no expone su path absoluto al gateway (los deep links de
  IDE requieren absolute paths).

## Helper programático

La lógica del skill está implementada en `hooks/lib/deep-links.js`. El skill
documenta **qué** generar; el helper genera **cómo**. Para uso desde código:

```js
const { construirDeepLink, soportaDeepLinks } = require('./lib/deep-links');

const url = construirDeepLink({
  ide:        'cursor',      // 'vscode' | 'vscode-insiders' | 'cursor' | 'codex' | 'jetbrains' | 'visualstudio'
  rutaAbsoluta: '/abs/path/a/archivo.js',
  linea:      42,
  columna:    8,
});
// → 'cursor://file//abs/path/a/archivo.js:42:8'

if (!url) {
  // El IDE solicitado no soporta deep links — usar fallback en texto plano
}
```

## Matriz de soporte por IDE

| IDE / App | Esquema | Soporte | Patrón canónico | Notas |
|---|---|---|---|---|
| **VS Code** | `vscode://` | Total | `vscode://file/<absoluteFile>:<line>:<column>` | Requiere VS Code instalado en máquina del receptor. |
| **VS Code Insiders** | `vscode-insiders://` | Total | `vscode-insiders://file/<absoluteFile>:<line>:<column>` | Esquema específico Insiders. |
| **Cursor** | `cursor://` | Total | `cursor://file/<absoluteFile>:<line>:<column>` | Fork de VS Code; misma forma. |
| **Codex Desktop** | `codex://` | Total | `codex://threads/<thread-uuid>`, `codex://settings` | Para hilos y settings; no archivos. |
| **JetBrains (IntelliJ/PyCharm/WebStorm/...)** | `jetbrains://` | Total | `jetbrains://<ide-id>/navigate/reference?project=<name>&path=<relPath>` | Requiere nombre del proyecto. Ver fila JetBrains abajo. |
| **JetBrains Toolbox URL** | `idea://` (deprecado), `jetbrains://idea/...` | Parcial | `jetbrains://idea/navigate/reference?project=<name>&path=<rel>:<line>` | Cada IDE tiene su `<ide-id>`: idea, pycharm, webstorm, goland, rubymine, etc. |
| **Visual Studio (Windows)** | (no estándar) | Sin esquema oficial | Usar CLI fallback: `devenv /edit <rutaAbsoluta>` | Solo Windows. |
| **Xcode** | `xcode://` | Parcial | `xcode://...` | Esquema existe; rutas de archivo no bien documentadas. NO confiable. |
| **Claude Desktop** | `claude://` | Desconocido | `claude://...` | Esquema registrado, rutas no documentadas. |
| **Codex CLI** (terminal) | n/a | No aplica | n/a | Es CLI; no abre archivos en IDE. Usar fallback texto plano. |
| **Cualquier app web** | n/a | No aplica | n/a | Si el destino es navegador, usar URL HTTP estándar. |

## Reglas de construcción

1. **Path absoluto obligatorio**. Deep links con rutas relativas no funcionan.
   El helper rechaza `path.relative` y retorna `null`.
2. **Encoding de paths con espacios**: aplicar `encodeURI` al path completo (no
   solo al filename). El helper lo hace automáticamente.
3. **Línea y columna son opcionales**: si no se especifican, el IDE abre al
   inicio del archivo. Línea 1, columna 1 es válido pero redundante.
4. **JetBrains requiere `proyecto`**: sin el nombre del proyecto, el deep link
   no resuelve. Si no se conoce, usar `vscode://` como fallback (la mayoría de
   los desarrolladores tienen VS Code instalado).
5. **NUNCA inventar esquemas**: si la matriz dice "No aplica" o "Desconocido",
   el helper retorna `null` y el caller debe usar texto plano.

## Formato según receptor

| Receptor | Forma del enlace |
|---|---|
| **Telegram** (Markdown V2) | `[abrir en IDE](cursor://file//abs/path:42:8)` |
| **Discord** | `[abrir en IDE](cursor://file//abs/path:42:8)` |
| **Slack** | `<cursor://file//abs/path:42:8\|abrir en Cursor>` (pipe-separado) |
| **Desktop notification** (Linux/macOS) | URL plana sin label; el notificador maneja el clic |
| **E-mail HTML** | `<a href="cursor://file//abs/path:42:8">abrir en Cursor</a>` |
| **Texto plano / fallback** | `archivo.js:42 (abrir manualmente)` |

## Gotchas observables

- **El receptor debe tener el IDE instalado**: un enlace `cursor://` no funciona
  si el receptor no tiene Cursor instalado. NO hay forma de detectarlo desde
  el emisor; documentar al usuario que el deep link es opt-in.
- **Slack tiene su propia sintaxis** `<url|label>`, no Markdown estándar. Mezclar
  los formatos rompe el clic.
- **Windows usa backslashes**: el path absoluto en Windows es
  `C:\Users\...\archivo.js`. El esquema `vscode://file/C:\\Users\\...` requiere
  doble-backslash en algunos casos; el helper normaliza con `path.resolve` +
  `encodeURI` para producir `vscode://file/C:/Users/...` (slashes forward) que
  VS Code/Cursor sí aceptan correctamente.
- **JetBrains URL Handler debe estar habilitado**: en JetBrains está bajo
  Settings → Tools → Web Browsers and Preview → "Use JetBrains as a
  redirect..." NO está activado por defecto en todas las distribuciones.

## Integración con SWL

Hoy se integra en `hooks/lib/gateway-notify.js` (opt-in): cuando un caller pasa
`payload.fileRef = { archivo, linea, columna }` Y existe `payload.idePreferido`,
el helper enriquece el mensaje con el deep link en el formato del adaptador
destino (Telegram / Discord / etc.).

Extensiones futuras (no implementadas hoy):

- `notificador-swl` (Telegram nativo): pasar `idePreferido` desde
  `instintos/perfil-usuario.yaml § ide_preferido`.
- `documentador-swl`: enlaces a archivos citados en docs generados.
- `revisor-codigo-swl`: enlaces a archivo:línea en reportes de hallazgos.

## Origen

Adaptado del skill `agent-deep-links` de
`temp/awesome-codex-skills-master/agent-deep-links/` (ComposioHQ, MIT) con:

- Frontmatter al estándar SWL (es-MX, `nivelRiesgo`, `exclusiones`,
  `herramientasPermitidas`).
- Matriz extendida con JetBrains (no estaba) y Visual Studio fallback.
- Sección "Formato según receptor" agregada para Telegram/Discord además del
  Slack original.
- Helper Node.js (`hooks/lib/deep-links.js`) que el repo origen no tenía.
- Sección "Integración con SWL" agregada.

Documentado en ADR-0029 (integración parcial awesome-codex-skills, Opción B).
