🧩 Estender o sistema

Comando que aceita URL de GitHub (repo, pasta ou SKILL.md direto), descarrega temporário com git archive, valida estrutura, mostra resultado e instala em .claude/skills/<categoria>/<nome>/.

Para esticares o catálogo conforme precisas, sem inflar com lixo. Cada passo é defensivo: validação antes de instalar, backup automático em conflito, teste de ativação no fim.

7 passos do fluxo · git archive · backup automático · conflict resolution · teste de ativação obrigatório.

Script chamado pelo comando. Faz 7 checks: 1) SKILL.md presente · 2) YAML frontmatter parseável · 3) name kebab-case com prefixo · 4) description 50-500 chars com verbo · 5) sem padrões destrutivos · 6) sem credenciais hardcoded · 7) references/ se conteúdo >2500 chars.

Para saberes porque uma skill é rejeitada. Cada bloqueio tem razão concreta — não é "magia opaca".

Bloqueante (recusa) vs aviso (instala mas avisa) · prefix obrigatório (marketing-, tool-, etc.) · description com verbo de intenção.

Lista de regex que o validador procura em scripts da skill: rm -rf / ou paths absolutos arriscados, eval $(...), curl | sh, dd if=, redirects para /dev/sd*, chmod 777.

Skills da comunidade podem ser maliciosas (ou simplesmente perigosas por descuido). O validador bloqueia o caso mais comum sem precisar de auditoria humana exaustiva.

Bloqueio automático = bom default · auditoria manual ainda recomendada para scripts complexos · skills sem scripts (só SKILL.md + references) têm risco quase zero.

Validador procura strings com formato típico de credenciais (sk-..., ghp_..., AKIA..., Bearer tokens) e regexes de email/password. Bloqueia se encontra — não queres importar segredos alheios.

Protege contra dois riscos: 1) usar credenciais de outra pessoa (legal e ético) · 2) ter credenciais expostas no teu repo se commitas a skill.

Credenciais sempre em .env · skills devem usar $ENV_VAR · skills com credenciais bloqueadas = autor da skill descuidado.

Doc em docs/skills-recommended.md com 35+ skills opcionais por categoria: Anthropic core (docx, xlsx, pptx, pdf), Marketing (10), CRO (7), SEO (4), Estratégia (9), Analytics (5).

É o teu menu. Filosofia "max 30 skills, não 1000" — qualidade > quantidade. Cada entrada testada ≥2 semanas em produção antes de entrar.

Camada 2 on-demand · revisão trimestral (skills obsoletas saem) · maintainer identificado · alternativa lean: claude-code-second-brain de Luis Pitik.

Se o argumento NÃO é URL mas nome simples (ex. /install-skill cognito), o comando procura em .claude/skills/_meta/_optional/<nome>/ e move para ativa (em _meta/ ou pasta apropriada).

Skills opcionais já incluídas no repo (como Cognito de Luis Pitik) ficam latentes em _optional/. Não pesam no descobrimento até as ativares. Modo atalho ativa sem baixar nada.

Skills latentes vs ativas · _optional/ não afeta o ranking semântico · ativação é só mover ficheiros + validar.

Standard aberto (Anthropic) que define como Claude expõe ferramentas de serviços externos: BD, repos, CRMs, docs, APIs. Um MCP server "publica" tools, Claude consome-as como se fossem nativas.

Sem MCPs, Claude está isolado. Com MCPs, faz queries SQL ao Supabase, lê issues do GitHub, cria páginas no Notion — tudo a partir do prompt.

Cliente (Claude Code) vs server (npx package) · stdio ou SSE como transport · tools com descrições semânticas · ativação por matching prompt-tool.

Comando que aceita 2 modos: 1) nome curto (/install-mcp context7) → procura em docs/mcps-curated.md e instala com config validada · 2) URL/JSON custom → valida estrutura, env vars e permissões antes de adicionar.

Para evitar a fricção de copiar JSONs de READMEs aleatórios. Lista curada = config testada + env vars documentadas + scopes claros.

.mcp.json no repo · env vars referenciadas (não literais) · scope read-only por defeito · separado de Sinapsis (que vive em ~/.claude/).

context7 (docs vivos de frameworks) · github (issues/PRs/ficheiros) · supabase (queries SQL, RLS) · notion (páginas, BDs) · firecrawl (scraping com bot-blockers).

Cobrem 80% das necessidades de um operador IA. Todos grátis (firecrawl tem 500 free). Validados em produção pelo maintainer.

context7 evita alucinação de APIs obsoletas · github PAT scope mínimo · supabase READ-ONLY token primeiro · firecrawl NÃO em .mcp.json (vai em .env).

Ficheiro JSON no root do repo com chave mcpServers contendo cada server: command (npx), args (package + flags), env (vars como $SUPABASE_TOKEN).

Para configurar/debugar manualmente quando o comando não chega. Para customizar por cliente (cada cliente pode ter o seu .mcp.json).

Env vars referenciadas com $ · permissões em .claude/settings.json · .mcp.json no .gitignore se tem secrets · per-client config.

Cada MCP ativo adiciona ~500-2000 tokens ao system prompt (descrições das suas tools). 10 MCPs = facilmente 10-20K tokens fixos por sessão.

Para não inflar contexto sem te dares conta. Sintoma: respostas piores em sessões longas porque o context window encheu de tool descriptions que não usaste.

5-7 MCPs ativos como regra · comenta os que não usas frequentemente · .mcp.json diferente por cliente · READ-ONLY antes de write.

Lista de categorias com risco elevado em docs/mcps-curated.md: write a redes sociais sem aprovação humana, MCPs com scopes opacos ou demasiado amplos, custom MCPs sem auditar o código.

Para não criares incidentes (post errado em LinkedIn pessoal, fuga de info no Slack, BD apagada). Maior risco do MCP = maior necessidade de gates humanos.

Aprovação humana para write em canais públicos · scopes mínimos · auditar código de MCPs custom · monitorizar custos de APIs pagas.

Skill que faz scaffolding de outra skill seguindo o padrão iAmasters: YAML frontmatter (name kebab-case, description 50-500 chars), secção "Quando se invoca", Process numerado, Edge cases, Output verifier gate.

Para a tua skill ser ativável (description bem feita), reutilizável (estrutura previsível), debugável (passos numerados). Skills mal feitas nunca se ativam ou ativam em momentos errados.

Prefix categorial (marketing-, tool-, automation-) · description com verbo de intenção · 3 testes da description (ativação, comprimento, unicidade) · progressive disclosure.

Regra: se vais repetir o mesmo padrão 3+ vezes nas próximas semanas E tem conhecimento separável da execução (templates, exemplos, checklists), graduar para skill. Senão, prompt direto.

Inflar skills com one-offs é o erro mais comum. 30 skills bem usadas >> 100 que nunca ativam. Promove só padrões validados.

Padrão repetido 3+ vezes · knowledge separável da execução · alternativa: slash command em .claude/commands/ para fluxos curtos.

Subpasta opcional dentro da skill com knowledge longo: examples.md (2-3 casos reais), checklist.md (QA antes de entregar), outros .md com domínio extenso. SKILL.md fica curto e referencia estes.

Progressive disclosure. Claude carrega SKILL.md sempre que avalia ativar; references/ só quando precisa. Skills com knowledge inline ficam pesadas no descobrimento.

references/ obrigatório se SKILL.md >2500 chars · examples.md ajuda muito a ativação correta · checklist.md = QA explícito.

Padrão em que uma skill invoca outra na secção "Quando se invoca" ou "Process". Exemplo: marketing-copywriting chama marketing-brand-voice para carregar voz, e tool-output-verifier antes de entregar.

Compõe skills pequenas em vez de fazer uma "skill mamute". Cada skill faz uma coisa bem; combinações emergem.

Nomear skills chamadas explicitamente · não criar dependências circulares · output-verifier como gate final em skills que entregam.

Skill tool-output-verifier verifica entregáveis contra: brand voice, tone, factualidade, formato pedido, ausência de "AI-tells" (frases robóticas, listagens excessivas). Deve ser chamada antes de declarar output final.

É o último filtro de qualidade. Sem ele, entregáveis saem "ok-mas-IA-óbvio" ou desalinhados com a voice. Com ele, pedem revisão menos vezes.

Skills com entregável final → chamada obrigatória · skills internas (que só preparam dados) → opcional · também invoca tool-humanizer para AI-tells.

Processo de PR: skill validada em produção ≥2 semanas, serve a ≥3 avatares (freelance-ia, agencia-marketing, formador-online, consultoria-b2b), sem dependências privadas, sem info confidencial. PR em inematds/iamasters-os.

Devolver é a melhor forma de aprender. Quando submetes, és forçado a generalizar, documentar, pensar em edge cases. O catálogo melhora-te a ti, não só o ecossistema.

Critérios objetivos · revisão trimestral · skills obsoletas saem · antes de PR, publica no teu GitHub e pede a 2-3 colegas para instalarem como teste.