Tool Structure

El layout estándar para una herramienta CLI. Los ficheros, los directorios, las convenciones y los requisitos de documentación.

Propósito

Esta página documenta el layout estándar para una herramienta CLI en el lab. Cada herramienta CLI sigue la misma estructura para que sea fácil de encontrar, leer, testear e integrar.

La estructura la impone la CLI Python tool template. Una herramienta nueva se crea copiando la plantilla y renombrando los ficheros relevantes.

Directory layout

tool-name/
├── __init__.py             ← vacío, marca el paquete
├── main.py                 ← CLI entry point
├── lib.py                  ← core logic (opcional)
├── cli.py                  ← comandos Click (opcional)
├── requirements.txt        ← dependencias Python
├── pyproject.toml          ← config del proyecto Python
├── package.json            ← AutoSkills (contexto del proyecto para el sub-agent)
├── README.md               ← documentación de usuario
├── TOOL.md                 ← especificación técnica
├── SKILL.md                ← activación por el Coordinator
├── AGENTS.md               ← instrucciones para el coding sub-agent
├── .env.example            ← variables de entorno de ejemplo
├── src/                    ← módulos adicionales (opcional)
│   ├── __init__.py
│   ├── api.py
│   ├── cache.py
│   └── ...
├── tests/                  ← tests unitarios
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_main.py
│   ├── test_lib.py
│   └── ...
├── skills/                 ← skills relacionados (opcional)
│   └── skill-name/
│       └── SKILL.md
├── docs/                   ← documentación adicional (opcional)
│   ├── README.md
│   ├── architecture.md
│   └── ...
└── examples/               ← ejemplos de uso (opcional)
    ├── example-1.md
    └── ...

La estructura es una generalización de las herramientas reales del lab (p. ej., torrent-finder, subtitle-finder).

Ficheros requeridos

Cada herramienta debe tener:

main.py — el CLI entry point.
requirements.txt — las dependencias Python.
pyproject.toml — la config del proyecto Python.
package.json — el contexto AutoSkills.
README.md — la documentación de usuario.
TOOL.md — la especificación técnica.
SKILL.md — el fichero de activación.
AGENTS.md — las instrucciones para el coding sub-agent.
tests/ — los tests unitarios.

Una herramienta sin estos ficheros está incompleta.

Ficheros opcionales

Una herramienta puede tener:

lib.py — el core logic, separado del pegamento CLI.
cli.py — los comandos Click, separados de main.py.
.env.example — variables de entorno de ejemplo.
src/ — módulos adicionales.
skills/ — skills relacionados.
docs/ — documentación adicional.
examples/ — ejemplos de uso.

Los ficheros opcionales se añaden cuando la herramienta crece. Una herramienta pequeña no los necesita.

Contenido de los ficheros

`main.py`

El CLI entry point. Estructura típica:

#!/usr/bin/env python3
"""Tool Name — descripción corta."""
 
import argparse
import json
import sys
from pathlib import Path
 
from tool_name.lib import do_something
 
 
def main():
    parser = argparse.ArgumentParser(description="Tool Name")
    parser.add_argument("query", help="The search query")
    parser.add_argument("--limit", type=int, default=10, help="Max results")
    parser.add_argument("--format", choices=["json", "text"], default="text")
    args = parser.parse_args()
 
    result = do_something(args.query, limit=args.limit)
 
    if args.format == "json":
        print(json.dumps(result, indent=2))
    else:
        for item in result:
            print(f"- {item['name']}: {item['url']}")
    return 0
 
 
if __name__ == "__main__":
    sys.exit(main())

El main.py debe ser pequeño. El core logic debe estar en lib.py.

`lib.py`

El core logic. Estructura típica:

"""Core logic for Tool Name."""
 
from typing import Any
import requests
 
 
def do_something(query: str, *, limit: int = 10) -> list[dict[str, Any]]:
    """La capacidad principal de la herramienta.
 
    Args:
        query: La query de búsqueda.
        limit: El número máximo de resultados.
 
    Returns:
        Una lista de diccionarios de resultado.
 
    Raises:
        ValueError: Si la query es inválida.
        ConnectionError: Si el upstream no está accesible.
    """
    if not query:
        raise ValueError("query is required")
 
    response = requests.get(
        "https://api.example.com/search",
        params={"q": query, "limit": limit},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

El lib.py es lógica pura. No depende de argparse ni de ningún framework CLI.

`requirements.txt`

Las dependencias Python. Una por línea:

requests>=2.28
beautifulsoup4>=4.11
lxml>=4.9
pydantic>=2.0

Pinea la versión mayor. Pinea la versión menor cuando la API es inestable.

`pyproject.toml`

La config del proyecto Python. Típico:

[project]
name = "tool-name"
version = "0.1.0"
description = "Descripción corta"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.28",
    "pydantic>=2.0",
]
 
[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "pytest-cov>=4.0",
]
 
[build-system]
requires = ["setuptools>=68.0"]
build-backend = "setuptools.build_meta"

`package.json` (AutoSkills)

El contexto AutoSkills. Es un pequeño fichero JSON que el coding sub-agent usa para entender el proyecto:

{
  "name": "tool-name",
  "description": "Descripción corta",
  "version": "0.1.0",
  "type": "python-cli",
  "entry": "main.py",
  "skills": ["python-patterns", "python-testing"],
  "tags": ["media", "search", "movies"]
}

El campo skills es la lista de skills que el sub-agent debe activar. El campo tags es la lista de tags que el Coordinator usa para encontrar la herramienta.

`README.md`

La documentación de usuario. Secciones típicas:

Título y descripción corta.
Instalación.
Uso (con ejemplos).
Configuración.
Limitaciones.
Licencia.

`TOOL.md`

La especificación técnica. El formato está documentado en Tool Spec.

`SKILL.md`

El fichero de activación. El formato está documentado en Tool Spec.

`AGENTS.md`

Las instrucciones para el coding sub-agent. Secciones típicas:

Project overview.
Convenciones.
Estructura de ficheros.
Cómo añadir un comando nuevo.
Cómo añadir una dependencia nueva.
Cómo correr los tests.

Tests

El directorio tests/ contiene los tests unitarios. El lab usa pytest para herramientas Python. Los tests se organizan por módulo:

tests/test_main.py — tests para el CLI entry point.
tests/test_lib.py — tests para el core logic.
tests/test_<module>.py — tests para módulos adicionales.

Los tests siguen las convenciones de Tool Spec → Tests.

Skills

Una herramienta puede tener uno o más skills asociados. Un skill es un fichero markdown que el Coordinator activa cuando la request del usuario coincide con las frases disparadoras del skill.

Los skills viven en skills/<skill-name>/SKILL.md. El formato está documentado en Tool Spec → SKILL.md.

Examples

El directorio examples/ contiene ejemplos de uso. Los ejemplos son ficheros markdown que muestran cómo usar la herramienta en un escenario específico.

El formato es:

# Example: <title>
 
## Scenario
[Qué hace el ejemplo.]
 
## Command
[El comando a correr.]
 
## Expected output
[Lo que el usuario debería ver.]