6.1 Install-skill | Curso iAmasters OS

📥 Anatomia do /install-skill

/install-skill <github-url> traz uma skill de outro repo para o teu, mas com validação prévia que bloqueia skills mal feitas. Anti-inflação por design.

7 passos do comando

Valida URL — é GitHub? aponta para pasta ou SKILL.md?
Descarrega temporário — scripts/validate-skill.sh usa git archive para subpasta
Valida estrutura — obrigatório (SKILL.md, YAML, description 50-500 chars, verbo de intenção), recomendado (references/ se >2500 chars), bloqueante (scripts destrutivos, credenciais hardcoded)
Mostra resultado ao operador — conflitos com locais, tamanho, validações
Instala localmente — backup automático se conflito, copia para .claude/skills/<categoria>/<nome>/, atualiza catalog e registry
Teste de ativação — reiniciar Claude, prompt que deveria ativar, oferece refinar description se falhar
Fecho — sugere /wrap-up, append em learnings.md se trouxe valor

Exemplo de validação

## Validação de skill

URL: https://github.com/scrapes/skills/humanizer
Skill: tool-humanizer (atenção: já tens skill local com esse nome!)
Tamanho: SKILL.md 2.1KB, references 4.5KB, scripts 0KB

### Validações
✅ SKILL.md presente
✅ YAML frontmatter correto
✅ description 187 chars (no intervalo)
⚠️ Conflito: já existe .claude/skills/tools/tool-humanizer/
✅ Sem código executável perigoso
✅ Sem credenciais hardcoded

### Ação
[1] Cancelar
[2] Substituir a tua local (com backup automático)
[3] Instalar como tool-humanizer-v2 (renomear)
[4] Ver diff vs a tua versão local

💡 Dica

Após instalar, reinicia Claude Code (Ctrl+C × 2 + claude). Sem reiniciar, o descobrimento de skills não vê a nova até à próxima sessão.

🔍 validate-skill.sh: os 7 checks

O script scripts/validate-skill.sh é o coração do comando. 7 checks objetivos, com saída clara: ✅ ok, ⚠️ aviso, 🚫 bloqueante.

Check	Validação	Tipo
1	SKILL.md existe na raiz da skill	Bloqueante
2	YAML frontmatter parseável (name + description)	Bloqueante
3	name kebab-case com prefixo categorial	Bloqueante
4	description 50-500 chars + verbo de intenção	Bloqueante
5	Sem padrões destrutivos em scripts	Bloqueante
6	Sem credenciais hardcoded	Bloqueante
7	references/ se SKILL.md >2500 chars	Aviso

📊 Prefixos categoriais válidos

• marketing- · brand voice, copy, conteúdo
• automation- · n8n, workflows
• strategy- · research, analysis
• tool- · utilities (humanizer, verifier, scraper)
• meta- · sistema (onboarding, deep-dive, skill-creator)

⚠️ Patterns destrutivos detetados

O check 5 procura regex de comandos perigosos em todos os scripts da skill. Não é exaustivo — é defesa em profundidade contra os casos mais comuns.

🚫 Bloqueados (regex)

• rm -rf / ou paths absolutos suspeitos ($HOME, ~/, /)
• eval $(...) · execução de strings dinâmicas
• curl ... | sh ou wget ... | bash
• dd if=... · disco direto
• Redirects para /dev/sd* · escrita raw em disco
• chmod 777 · permissões abertas
• find ... -delete sem path estrito

💡 Skills sem scripts = risco quase zero

A maioria das skills úteis (marketing, brand voice, content) não precisam de scripts executáveis — só SKILL.md + references/. Essas não disparam o check 5. Skills com scripts requerem mais atenção.

📊 Falsos positivos vs falsos negativos

Falso positivo (skill segura bloqueada): podes pedir override explícito ao maintainer ou modificar localmente após auditar.

Falso negativo (skill perigosa passa): o regex pode ser evadido com ofuscação. Para skills críticas, audita visualmente os scripts antes de instalar.

🔐 Deteção de credenciais hardcoded

O check 6 procura padrões típicos de credenciais em todos os ficheiros da skill. Protege dois riscos: usar credenciais alheias (legal/ético) e expor as tuas se commitas.

Padrão	Exemplo	Origem típica
`sk-...`	`sk-proj-abc123...`	OpenAI
`ghp_...`	`ghp_xyz...`	GitHub PAT
`AKIA...`	`AKIA1234567890ABCDEF`	AWS Access Key
`Bearer ...`	`Bearer eyJhbGc...`	JWT genérico
`xoxb-...`	`xoxb-1234-...`	Slack bot token
`fc-...`	`fc-abcdef...`	Firecrawl

✓ Correto

curl -H "Authorization: \
  Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/...

# Variável referenciada, valor em .env

✗ Bloqueado

curl -H "Authorization: \
  Bearer sk-proj-abc123def" \
  https://api.openai.com/v1/...

# Credencial literal no script

💡 Skill com credenciais bloqueada = autor descuidado

É sinal de práticas pobres do autor da skill. Mesmo que não fosse maliciosa, instala alternativa ou contacta o autor pedindo correção.

📚 Catálogo curado (docs/skills-recommended.md)

O doc docs/skills-recommended.md é o teu menu de Camada 2: 35+ skills opcionais por categoria. Filosofia: "max 30 skills, não 1000".

🎯 Anthropic core (4)

docx, xlsx, pptx, pdf · instaláveis via /plugin install anthropic-skills. Recomendação: instalar SEMPRE se trabalhas com Office.

📣 Marketing (10)

copywriting, copy-editing, content-strategy, email-sequence, social-content, ad-creative, launch-strategy, paid-ads, cold-email, micro-copy.

🎯 CRO (7)

page-cro, form-cro, signup-flow-cro, popup-cro, paywall-upgrade-cro, onboarding-cro, ab-test-setup.

🔍 SEO (4)

seo-audit, ai-seo (AEO/GEO/LLMO), schema-markup, programmatic-seo.

📊 Por que catálogo curado vs marketplace livre

•Filtro de qualidade: cada entrada testada ≥2 semanas em produção
•Anti-inflação cognitiva: 1000 skills paralisa, 30 bem escolhidas habilitam
•Revisão trimestral: skills obsoletas saem, novas validadas entram
•Maintainer identificado: revê PRs — não anonimato

💡 Alternativa lean

Se preferes minimal sem skills curadas, claude-code-second-brain de Luis Pitik (autor de Sinapsis) é a versão lean: prompt → entrevista → ficheiros context/ + decisions-log. Produtos irmãos, não concorrência.

🔑 Modo "atalho opcional" — /install-skill cognito

Se o argumento não é URL mas nome simples (ex. /install-skill cognito), o comando procura em .claude/skills/_meta/_optional/<nome>/ e ativa-a sem baixar nada.

Fluxo do modo atalho

/install-skill cognito

1. Procura em .claude/skills/_meta/_optional/cognito/
2. Se existe → valida (mesmos 7 checks)
3. Move para .claude/skills/_meta/cognito/
4. Atualiza skills-catalog.json
5. Update do registry em CLAUDE.md
6. Reinicia para teste de ativação

📊 Skills latentes vs ativas

•Latentes (_optional/): no repo mas Claude não as vê. Não afetam ranking semântico.
•Ativas (em _meta/, marketing/, etc.): descobertas e ativadas por description matching.
•Useful quando há skills relacionadas mas que canibalizariam descobrimento se ativas todas em simultâneo.

💡 Exemplo: Cognito

Cognito (Sistema Operativo de Pensamento de Luis Pitik) vem vendorizado em _optional/ porque pesa muito no descobrimento e nem todos os operadores o usam. Ativa com /install-skill cognito apenas se queres a sua framework de pensamento estruturada.

✅ Resumo do Módulo

✓

/install-skill em 7 passos — URL → validação → instalar → teste ativação

✓

validate-skill.sh com 7 checks — 6 bloqueantes + 1 aviso (references/ se grande)

✓

Patterns destrutivos bloqueados — rm -rf, eval, curl|sh, dd, chmod 777

✓

Deteção de credenciais hardcoded — sk-, ghp_, AKIA, Bearer, xoxb, fc-

✓

Catálogo curado > marketplace livre — qualidade ≥2 semanas, revisão trimestral

✓

Modo atalho para _optional/ — /install-skill cognito ativa skill latente

Próximo Módulo:

6.2 — Install-mcp: MCP servers (context7, github, supabase, notion, firecrawl) com lista curada, .mcp.json, token budget.

← Voltar para Trilha 6 Módulo 6.2 →