Ir para o conteúdo

Skill BotCity Python Pro

A skill botcity-python-pro transforma o Claude num par de programação especializado em automações BotCity de nível produção. Aplica padrões modernos de Python 3.11+ adaptados à realidade de RPA: segurança de credenciais, tratamento de erro em camadas, separação UI/lógica e respeito ao formato de deploy do Runner BotCity. Funciona em português e inglês.

Pré-requisitos

  • Claude Code instalado e configurado
  • Python 3.11 ou superior
  • Projeto BotCity existente ou intenção de criar um do zero
  • Acesso ao BotCity Maestro (necessário para deploy em produção)
  • Dependências de runtime pinadas no requirements.txt do projeto:
pip install botcity-framework-web botcity-maestro-sdk pydantic python-dotenv

Instalar a skill

Copie o arquivo botcity-python-pro/skill.md para a pasta de skills do Claude Code:

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

Nota

A skill é ativada automaticamente quando o Claude detecta contexto BotCity — código com DesktopBot, WebBot, botcity-maestro-sdk, referências a DataPool ou Runner. Você não precisa invocá-la manualmente.

Escolher o modo de operação

A skill opera em quatro modos. Declare explicitamente qual você precisa no início da conversa:

Modo Quando usar O que esperar
Scaffold Projeto novo do zero Estrutura src/ completa, requirements.txt pinado, esqueleto de testes
Refactor Melhorar bot existente Diagnóstico estruturado (Critical/Important/Nice-to-have) antes de alterar código
Fix Bug pontual Correção cirúrgica sem refatoração oportunista
Review Feedback estruturado Lista categorizada de findings sem aplicar mudanças

Dica

Seja explícito: "bot novo do zero" e "só quero corrigir esse timeout" geram respostas muito diferentes.

Criar um bot do zero

Use um prompt descritivo com as responsabilidades do bot:

Cria um bot BotCity do zero que:
- Consome itens de um DataPool chamado "invoices_to_process"
- Faz login num portal web usando credenciais do Maestro
- Baixa o PDF de cada NF e sobe como artifact
- Lida com NF inválida marcando o item como erro sem abortar

A skill gera a seguinte estrutura de projeto:

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/

Atenção

O Runner BotCity lê requirements.txt, não pyproject.toml. Se você usar uv, execute uv export --no-dev --no-hashes --format requirements-txt > requirements.txt antes de empacotar o .zip para deploy.

Refatorar um bot existente

Cole o código diretamente na conversa e peça revisão:

Revisa esse bot pra mim. É um Selenium puro que migramos pra BotCity
mês passado e tá dando problema em produção. [cola código]

A skill executa o checklist de diagnóstico e retorna findings estruturados:

## Findings

### Critical (2)
1. Hardcoded API key em src/api_client.py:14 — mover para Maestro Credentials
2. CPF logado sem mascaramento em src/services/customer.py:47 — aplicar mask_cpf()

### Important (3)
...

### Suggested order
1. Corrigir Criticals (segurança)
2. Importants 1-3 (confiabilidade)
3. Niceties podem esperar

Qual você quer que eu trate primeiro?

Configurar credenciais e DataPool

A skill gera o padrão canônico de bootstrap com fallback para desenvolvimento 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 com tratamento de erro em três níveis:

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

Atenção

Em caso de FatalError, chame entry.unhold() antes de re-lançar a exceção. Sem isso, o item fica retido no pool e é perdido.

Resultado esperado

Ao usar a skill botcity-python-pro, seu projeto terá:

  • requirements.txt com todas as dependências de runtime pinadas com ==, sem ferramentas de dev
  • Separação em três camadas: pages/ (UI/seletores), services/ (lógica de negócio), domain/ (modelos Pydantic)
  • Hierarquia de exceções customizadas: RecoverableError, BusinessError, FatalError
  • Credenciais consumidas via Maestro SDK com fallback .env para execução local
  • Dados de entrada validados com Pydantic antes de qualquer processamento
  • PII (CPF, e-mail, tokens) mascarados em logs e artifacts
  • Type hints aplicados com rigor em services/ e domain/, tolerantes em pages/
  • Testes unitários cobrindo 60-70% de services/, domain/ e utils/