Skill BotCity Python Pro

La skill botcity-python-pro convierte a Claude en un par de programación especializado en automatizaciones BotCity de nivel producción. Aplica patrones modernos de Python 3.11+ adaptados a la realidad de RPA: seguridad de credenciales, manejo de errores en capas, separación UI/lógica y respeto al formato de deploy del Runner BotCity. Funciona en portugués e inglés.

---

Prerrequisitos

• Claude Code instalado y configurado
• Python 3.11 o superior
• Proyecto BotCity existente o intención de crear uno desde cero
• Acceso a BotCity Maestro (necesario para deploy en producción)
• Dependencias de runtime fijadas en el requirements.txt del proyecto:

pip install botcity-framework-web botcity-maestro-sdk pydantic python-dotenv

---

Instalar la skill

Copia el archivo botcity-python-pro/skill.md a la carpeta de skills de Claude Code:

cp botcity-python-pro/skill.md ~/.claude/skills/botcity-python-pro.md

Nota

La skill se activa automáticamente cuando Claude detecta contexto BotCity — código con DesktopBot, WebBot, botcity-maestro-sdk, referencias a DataPool o Runner. No es necesario invocarla manualmente.

---

Elegir el modo de operación

La skill opera en cuatro modos. Declara explícitamente cuál necesitas al inicio de la conversación:

Modo	Cuándo usar	Qué esperar
Scaffold	Proyecto nuevo desde cero	Estructura src/ completa, requirements.txt fijado, esqueleto de pruebas
Refactor	Mejorar bot existente	Diagnóstico estructurado (Critical/Important/Nice-to-have) antes de modificar el código
Fix	Bug puntual	Corrección quirúrgica sin refactorización oportunista
Review	Feedback estructurado	Lista categorizada de hallazgos sin aplicar cambios

Consejo

Sé explícito: "bot nuevo desde cero" y "solo quiero corregir este timeout" generan respuestas muy diferentes.

---

Crear un bot desde cero

Usa un prompt descriptivo con las responsabilidades del bot:

Crea un bot BotCity desde cero que:
- Consuma ítems de un DataPool llamado "invoices_to_process"
- Inicie sesión en un portal web usando credenciales del Maestro
- Descargue el PDF de cada factura y lo suba como artifact
- Maneje facturas inválidas marcando el ítem como error sin abortar

La skill genera la siguiente estructura de proyecto:

my_bot/
├── bot.py
├── requirements.txt
├── pyproject.toml
├── README.md
├── .env.example
├── .gitignore
├── resources/
├── src/
│   ├── config.py
│   ├── pages/
│   ├── services/
│   ├── domain/
│   ├── utils/
│   └── exceptions.py
└── tests/
    ├── unit/
    └── fixtures/

Atención

El Runner BotCity lee requirements.txt, no pyproject.toml. Si usas uv, ejecuta uv export --no-dev --no-hashes --format requirements-txt > requirements.txt antes de empaquetar el .zip para el deploy.

---

Refactorizar un bot existente

Pega el código directamente en la conversación y solicita una revisión:

Revisa este bot para mí. Es un Selenium puro que migramos a BotCity
el mes pasado y está dando problemas en producción. [pega el código]

La skill ejecuta el checklist de diagnóstico y devuelve hallazgos estructurados:

## Findings

### Critical (2)
1. API key hardcoded en src/api_client.py:14 — mover a Maestro Credentials
2. CPF registrado sin enmascaramiento en src/services/customer.py:47 — aplicar mask_cpf()

### Important (3)
...

### Suggested order
1. Corregir Criticals (seguridad)
2. Importants 1-3 (confiabilidad)
3. Niceties pueden esperar

¿Cuál quieres que trate primero?

---

Configurar credenciales y DataPool

La skill genera el patrón canónico de bootstrap con fallback para desarrollo local:

BotMaestroSDK.RAISE_NOT_CONNECTED = False
maestro = BotMaestroSDK.from_sys_args()

def get_secret(label: str, key: str) -> str:
    try:
        return maestro.get_credential(label=label, key=key)
    except Exception:
        load_dotenv()
        value = os.getenv(f"{label.upper()}_{key.upper()}")
        if not value:
            raise CredentialError(f"Missing credential: {label}/{key}")
        return value

Para consumo de DataPool con manejo de errores en tres niveles:

pool = maestro.get_datapool(label="invoices_to_process")

while pool.has_next():
    entry = pool.next(task_id=maestro.task_id)
    if entry is None:
        break
    try:
        item = InvoiceItem.model_validate(entry.values)
        service.process_invoice(item)
        entry.report_done()
    except BusinessError as e:
        entry.report_error(message=str(e))
    except FatalError:
        entry.unhold()
        raise

Atención

En caso de FatalError, llama a entry.unhold() antes de relanzar la excepción. Sin esto, el ítem queda retenido en el pool y se pierde.

---

Resultado esperado

Al usar la skill botcity-python-pro, tu proyecto tendrá:

• requirements.txt con todas las dependencias de runtime fijadas con ==, sin herramientas de dev
• Separación en tres capas: pages/ (UI/selectores), services/ (lógica de negocio), domain/ (modelos Pydantic)
• Jerarquía de excepciones personalizadas: RecoverableError, BusinessError, FatalError
• Credenciales consumidas via Maestro SDK con fallback .env para ejecución local
• Datos de entrada validados con Pydantic antes de cualquier procesamiento
• PII (CPF, e-mail, tokens) enmascarados en logs y artifacts
• Type hints aplicados con rigor en services/ y domain/, tolerantes en pages/
• Pruebas unitarias cubriendo 60-70% de services/, domain/ y utils/