Tool Spec

El formato y contenido de un fichero TOOL.md. La especificación técnica que el agente lee para entender el contrato de una herramienta.

Propósito

Esta página documenta el formato y contenido de un fichero TOOL.md. Un TOOL.md es la especificación técnica que el agente lee para entender el contrato de una herramienta: qué hace, cómo invocarla, qué devuelve y qué puede fallar.

Un TOOL.md es obligatorio para cada herramienta del lab. El formato es consistente en todas las herramientas; esto hace que sea fácil para el agente leer el TOOL.md de una herramienta nueva y saber qué esperar.

Secciones requeridas

Cada TOOL.md debe tener las siguientes secciones:

Título y descripción corta.
Purpose. Una descripción de un párrafo de qué hace la herramienta.
Commands. Los comandos CLI que soporta la herramienta.
Inputs. Los inputs que toma cada comando.
Outputs. Los outputs que devuelve cada comando.
Data flow. Un diagrama o descripción de cómo la herramienta procesa los inputs.
Configuration. La configuración que requiere la herramienta.
Dependencies. Las dependencias de la herramienta.
Tests. Cómo se testea la herramienta.
Failure modes. Qué puede fallar y cómo recuperarse.

Las secciones opcionales incluyen:

Examples. Ejemplos de uso.
Limitations. Limitaciones conocidas.
References. Enlaces a docs relacionadas.

Plantilla

# Tool Spec: <tool-name>
 
## Purpose
<Descripción de un párrafo.>
 
## Commands
 
### Command 1 (placeholder)
- Input: <args>
- Output: <output format>
- Source: <de dónde vienen los datos>
- Filters: <filtros aplicados>
 
### Command 2 (placeholder)
- ...
 
## Data flow
 
```text
<Diagrama ASCII o mermaid del data flow.>
```
 
## Configuration
 
| Variable | Default | Purpose |
| -------- | ------- | ------- |
| ...      | ...     | ...     |
 
## Dependencies
 
- `<dependency-1>`: <version>
- `<dependency-2>`: <version>
 
## Tests
 
Los tests de la herramienta están en `tests/`. El comando de test es
`<test-command>`.
 
## Failure modes
 
| Failure | Result | Recovery |
| ------- | ------ | -------- |
| ...     | ...    | ...      |

Ejemplo: `torrent-finder` TOOL.md

Un ejemplo real. torrent-finder busca películas/series vía BitTorrent.

# Tool Spec: torrent-finder
 
## Purpose
Busca películas/series vía BitTorrent y devuelve magnet URLs. El Coordinator corre esto para encontrar contenido, presenta los resultados y abre el magnet elegido en Transmission.
 
## Commands
 
### `search <query>`
- Input: query de búsqueda (nombre de película/serie + filtros de calidad)
- Output: lista de magnets con fuente y título
- Sources: solidtorrents.net, 1377x.to, bt4g.com
- Filtrar resultados por calidad: 4K, 1080p, HDR, DV, x265, x264
 
### `open --magnet <url>`
- Input: magnet URL completo
- Output: abre en Transmission (comando `open` de macOS)
- `--dry-run` opcional para previsualizar sin abrir
 
## Data flow
 
```text
User query (p. ej., "Snatch 2000 4K")
    ↓
Build search URLs for each source
    ↓
HTTP GET con headers tipo browser
    ↓
Extract magnets from HTML (regex)
    ↓
Filter by quality
    ↓
Return results
```
 
## Configuration
 
| Variable           | Default     | Purpose                          |
| ------------------ | ----------- | -------------------------------- |
| `TORRENT_SOURCES`  | (3 sources) | Las fuentes a consultar.         |
| `TORRENT_TIMEOUT`  | `30`        | Timeout por request en segundos. |
| `TORRENT_UA`       | (random)    | El string del user agent.        |
 
## Dependencies
 
- `requests>=2.28`: cliente HTTP.
- `beautifulsoup4>=4.11`: parsing de HTML.
- `lxml>=4.9`: parser de XML/HTML.
 
## Tests
 
Los tests están en `tests/`. El comando de test es
`pytest tests/`. Los tests usan respuestas HTTP mockeadas para evitar golpear las fuentes reales.
 
## Failure modes
 
| Failure                          | Result                                  |
| -------------------------------- | --------------------------------------- |
| Todas las fuentes inaccesibles   | Devolver lista vacía con un warning.    |
| No hay resultados para la query  | Devolver lista vacía.                   |
| La fuente devuelve 4xx           | Saltar la fuente; probar la siguiente.  |
| La fuente devuelve 5xx           | Reintentar una vez; saltar si sigue.    |
| El magnet URL es malformed       | Saltar la entrada; loguear el issue.    |

SKILL.md

El fichero SKILL.md es el fichero de activación. Lo carga el skill loader del Coordinator cuando la request del usuario coincide con las frases disparadoras del skill.

El formato es:

---
name: <skill-name>
description: <Descripción de un párrafo.>
---
 
# <Skill Name>
 
## When to Use This Skill
 
[Frases disparadoras y condiciones.]
 
## Workflow
 
1. Paso 1
2. Paso 2
3. ...
 
## Inputs
 
[Lo que el skill necesita.]
 
## Outputs
 
[Lo que el skill produce.]
 
## Failure modes
 
[Lo que puede fallar.]

Los campos name y description del YAML frontmatter son las frases disparadoras que usa el Coordinator. El body es el workflow que sigue el Coordinator.

Tests

Los tests de la herramienta viven en tests/. Las convenciones de test:

Un fichero de test por módulo. test_main.py para main.py, test_lib.py para lib.py, etc.
Usa pytest. El test runner es pytest.
Mockea dependencias externas. Las llamadas HTTP, el file I/O y las llamadas a subprocess se mockean.
Cubre el happy path y los paths de fallo. Cada comando se testea tanto en éxito como en fallo.
Usa fixtures para setup compartido. El fichero conftest.py contiene las fixtures compartidas.

El objetivo de cobertura es 70% mínimo.

Añadir una herramienta nueva

Para añadir una herramienta nueva:

Copia la CLI Python tool template.
Actualiza el nombre de la herramienta en todos los ficheros.
Implementa main.py y lib.py.
Escribe los tests.
Escribe los README.md, TOOL.md, SKILL.md y AGENTS.md.
Registra la herramienta en el tools.json del proyecto.
Corre los tests.
Verifica que la herramienta la puede invocar el Coordinator.