botcity-python-pro

Skill do Claude para desenvolvimento profissional de automações BotCity em Python. Claude skill for professional BotCity automation development in Python.

🇧🇷 Português · 🇺🇸 English

---

🇧🇷 Português

O que é

Uma skill que 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 pra realidade de RPA — sem rigor irrelevante, mas firme no que importa: 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 e cobre 4 modos de trabalho: criar do zero, refatorar, corrigir bug pontual e revisar código.

Quando ativa

A skill ativa automaticamente quando você conversa com o Claude sobre automações BotCity. Você não precisa invocá-la.

Ativa em prompts como:

• "Criar um bot da BotCity que..."
• "Refatorar essa automação em Python"
• "Revisar meu bot"
• "Como tratar erro no Maestro?"

Também ativa quando o BotCity não é nomeado mas o contexto fica claro (código com DesktopBot, menção a botcity-maestro-sdk, DataPool, Runner, etc.).

Os 4 modos

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

O que ela garante no seu código

• ✅ requirements.txt como manifest do Runner (não pyproject.toml)
• ✅ Separação em 3 camadas: pages/ (UI), services/ (lógica), domain/ (Pydantic)
• ✅ Tratamento de erro em 3 níveis: RecoverableError, BusinessError, FatalError
• ✅ Credenciais via Maestro SDK com fallback .env para dev local
• ✅ Pydantic em fronteiras de dados
• ✅ Mascaramento de PII em logs e screenshots
• ✅ Type hints pragmáticos (strict em lógica, tolerante em UI)
• ✅ Testes onde valem a pena (lógica pura, não UI)

Como usar bem

1. Seja explícito sobre o contexto. "Bot novo do zero" vs "só quero corrigir esse timeout" muda muito a resposta.
2. Cole código quando refatorar/revisar. Não descreva — cole.
3. Aceite ou ajuste o modo. Quando Claude indicar "vou tratar como refactor mode", confirme ou corrija logo no início.
4. A skill é opinativa, mas adapta. Se sua estrutura é diferente, fala — ela ajusta.

Templates de prompt

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

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]

Tô com um WebBot que dá ElementNotFoundException aleatório no login.
Já tem retry mas continua falhando. Como diagnostico?

Setup mínimo de projeto BotCity novo com uv localmente — quero usar
uv pra desenvolvimento mas garantir que o Runner vai funcionar no deploy.

Limites — o que NÃO faz

• ❌ Não substitui a documentação oficial (documentation.botcity.dev)
• ❌ Não é tutorial de Python básico
• ❌ Não é catálogo de features BotCity
• ❌ Não acessa o Maestro real (sem credenciais, sem deploy, sem leitura de tasks)

Troubleshooting rápido

Problema	Solução
Saiu refatorando quando eu pedi revisão	"para, lista os problemas primeiro"
Sugeriu pyproject.toml como manifest de deploy	Lembre: Runner usa requirements.txt
Respondeu no idioma errado	"responde em português, por favor"
Sugeriu mockar Selenium pra teste	Reforce o contexto BotCity, a §8 da skill é contra isso
Muito rigor pra bot simples interno	Fala — ela adapta

Arquivos deste pacote

• botcity-python-pro.md — a skill em si (instalar no Claude)
• README.md — este arquivo (PT + EN)
• Prompts de teste (opcional, pra validar a skill no seu ambiente)

---

🇺🇸 English

What it is

A Claude skill that turns the assistant into a pair-programmer specialized in production-grade BotCity automations. It applies modern Python (3.11+) standards adapted to the realities of RPA — without irrelevant rigor, but firm on what matters: credential safety, layered error handling, UI/logic separation, and respect for the BotCity Runner's deployment format.

Works in Portuguese and English and covers 4 working modes: build from scratch, refactor, fix a specific bug, and review code.

When it activates

The skill activates automatically when you talk to Claude about BotCity automations. You don't need to invoke it.

Activates on prompts like:

• "Create a BotCity bot that..."
• "Refactor this Python automation"
• "Review my bot"
• "How do I handle errors with Maestro?"

Also activates when BotCity isn't named but the context is clear (code with DesktopBot, mention of botcity-maestro-sdk, DataPool, Runner, etc.).

The 4 modes

Mode	When to use	What to expect
Scaffold	New project	Full src/ layout, pinned requirements.txt, tests
Refactor	Improve existing bot	Checklist diagnosis (Critical/Important/Nice-to-have) before changing code
Fix	Specific bug	Surgical fix, no opportunistic refactoring
Review	Structured feedback	Categorized list of findings, no changes applied

What it guarantees in your code

• ✅ requirements.txt as the Runner's manifest (not pyproject.toml)
• ✅ Three-layer separation: pages/ (UI), services/ (logic), domain/ (Pydantic)
• ✅ Three-level error handling: RecoverableError, BusinessError, FatalError
• ✅ Credentials via Maestro SDK with .env fallback for local dev
• ✅ Pydantic at data boundaries
• ✅ PII masking in logs and screenshots
• ✅ Pragmatic type hints (strict on logic, lenient on UI)
• ✅ Tests where they're worth it (pure logic, not UI)

How to use it well

1. Be explicit about context. "New bot from scratch" vs "I just want to fix this timeout" changes the answer a lot.
2. Paste code when refactoring or reviewing. Don't describe — paste.
3. Accept or adjust the mode. When Claude indicates "I'll treat this as refactor mode", confirm or correct early.
4. The skill is opinionated, but adapts. If your structure is different, say so — it adjusts.

Prompt templates

Create a BotCity bot from scratch that:
- Consumes items from a DataPool named "invoices_to_process"
- Logs into a web portal using Maestro credentials
- Downloads each invoice's PDF and uploads it as an artifact
- Handles invalid invoices by marking the DataPool item as error without aborting

Review this bot for me. It's pure Selenium that we migrated to BotCity
last month and it's causing problems in production. [paste code]

I have a WebBot that throws random ElementNotFoundException on login.
There's already a retry but it still fails. How do I diagnose this?

Minimal setup for a new BotCity project with uv locally — I want to use
uv for development but guarantee the Runner will work on deploy.

Limits — what it does NOT do

• ❌ Not a substitute for official docs (documentation.botcity.dev)
• ❌ Not a Python tutorial
• ❌ Not a BotCity feature catalog
• ❌ No access to your live Maestro (no credentials, no deploys, no task reads)

Quick troubleshooting

Problem	Fix
Started refactoring when I asked for a review	"stop, list the issues first"
Suggested pyproject.toml as deployment manifest	Remember: Runner uses requirements.txt
Replied in the wrong language	"please reply in [language]"
Suggested mocking Selenium for tests	Reinforce BotCity context, §8 of the skill is against this
Too much rigor for a simple internal bot	Say so — it adapts

Files in this package

• botcity-python-pro.md — the skill itself (install in Claude)
• README.md — this file (PT + EN)
• Test prompts (optional, to validate the skill in your environment)

---

📦 Installation / Instalação

Claude.ai

1. Open Claude.ai → Settings → Capabilities → Skills
2. Upload botcity-python-pro.md (or the packaged .skill file)
3. The skill will appear in your available skills list

Claude Code

Place botcity-python-pro.md in ~/.claude/skills/ (or your project-specific skills folder).

---

🔄 Version / Versão

v2.0.0 — Bilingual support (PT/EN), requirements.txt as Runner source of truth, refactor mode with categorized findings, PII masking patterns, four-mode operation.

v1.0.0 — Initial release as generic python-pro skill (deprecated).

---

_{Criado e mantido por Giulia Real · BotCity
Created and maintained by Giulia · BotCity}