Módulo 3.5 · Criando uma Skill Própria

🎯 Quando criar uma skill nova vs. estender

Decisão antes do código.

O que é

Heurística:

Estende: se a skill existente cobre 70%+ do que você precisa, customize via DESIGN.md ou checklist.md
Cria nova: se < 70% — workflow é genuinamente diferente, anti-patterns próprios, side-files distintos

Exemplo: "landing pra cursos online" — saas-landing serve com customização (estende). "Newsletter email" — workflow diferente (HTML inline, table-based) → cria nova.

Por que aprender

Skill nova = ~4 horas pra fazer bem. Estender = 30 minutos. Erre essa decisão = perde tempo. Default: estende. Exception: cria.

Conceitos-chave

70% rule: threshold de cobertura
Estender = custom checklist.md + custom DESIGN.md
Criar = nova SKILL.md + side-files
Sinal "criar": workflow começa com algo que skill base não faz (ex: importar CSV)

📁 O template de pasta

<skill-name>/{SKILL.md, assets/, references/}.

O que é

landing-curso/
├── SKILL.md                  # frontmatter + workflow Markdown
├── assets/
│   └── template.html         # HTML seed para o agente
└── references/
    ├── layouts.md            # 5-8 layouts paste-ready (hero edu, modules grid, instructor)
    └── checklist.md          # P0 (CTAs especificos pra curso, pricing claro)

Por que aprender

Padrão de pasta é o que torna skill portátil. Outro dev clona seu repo, copia pasta inteira pra ~/.claude/skills/, funciona imediatamente. Sem padrão, ninguém reusa.

Conceitos-chave

name = pasta name: kebab-case
SKILL.md obrigatório
assets/ opcional: só se há template HTML
references/ opcional: só se há vocabulário extra

📝 Frontmatter passo a passo

name, description, triggers (multi-idioma), od: extensions.

O que é

---
name: landing-curso
description: Landing page para cursos online educacionais
triggers:
  - "landing curso"
  - "página de curso"
  - "course landing"
  - "online course page"
od:
  mode: prototype
  platform: web
  scenario: education
  preview: { aspect: "16:9" }
  design_system: editorial-monocle
  default_for: ["education", "online-course"]
  example_prompt: "Faça uma landing pra um curso de cybersegurança"
---

Por que aprender

Triggers em multi-idioma é crucial pra adoção global. Um time brasileiro + um time americano usam o mesmo skill. example_prompt aparece no picker — ajuda usuário a entender o que esperar.

Conceitos-chave

name: kebab-case, único por escopo
description: 1 linha, voz ativa
triggers: 3-7 frases, idiomas-alvo
od.mode: prototype | deck | scenario
od.example_prompt: mostra no picker

🌱 `assets/template.html` — boas práticas de seed

Tokens em :root, comentários por seção.

O que é

Template é o "esqueleto" que o agente abre primeiro. Inclui:

Tokens em :root — agente troca, não inventa de novo
Comentários  — marcam seções editáveis
Layout esqueleto — divs vazios com classes que indicam estrutura
Placeholders honestos — <span>[Nome do curso]</span>

<!DOCTYPE html>
<html>
<style>
:root { --bg: oklch(98% 0.01 90); --fg: oklch(15% 0 0); --accent: oklch(58% 0.15 35); }
</style>
<body>
<!-- HERO: nome do curso + tagline + CTA -->
<section class="hero">[content]</section>

<!-- MODULES GRID: 4-8 módulos -->
<section class="modules">...</section>
</body></html>

Por que aprender

Template sem :root tokens = agente inventa cores em cada geração. Template sem comentários = agente bagunça ordem de seções. Bom template economiza 50% dos retrabalhos.

Conceitos-chave

:root tokens: --bg, --fg, --accent (mínimo)
Section comments: guiam onde editar
Skeleton, não final: agente preenche, não só copia
Honest placeholders: [content] > lorem ipsum

📋 `references/layouts.md` — paste-ready

Por que paste-ready importa.

O que é

Layouts em references/layouts.md são HTML paste-ready — o agente copia o snippet, ajusta tokens/conteúdo, injeta. Não é descrição em prosa; é HTML real.

# layouts.md

## Hero — Curso edu

```html
<section class="hero" style="padding: 96px 24px;">
  <h1 style="font-size: 64px; line-height: 1.05;">[Nome do curso]</h1>
  <p style="font-size: 22px; color: var(--muted);">[Tagline em 1 frase]</p>
  <a href="#enroll" class="cta">Matricular →</a>
</section>
```

## Modules Grid — 4 to 8 módulos

```html
<section class="modules grid">
  <article>...</article>  <!-- repete -->
</section>
```

Por que aprender

Modelos LLM são bons em adaptar HTML existente, ruins em produzir do zero. Paste-ready > descrição. "Cole isso, ajuste content" funciona; "faça uma seção hero com X" produz variação.

Conceitos-chave

5-8 layouts: sweet spot
HTML real, não markdown: direto no template
Style inline: não dependa de CSS externo
Comments dentro: guiar onde adapt

✅ `references/checklist.md` — escrevendo P0 que vale

Mensurabilidade vs intenção.

O que é

P0 que vale a pena tem verificabilidade:

✅ Bom P0: "border-radius máximo 4px" (verificável: regex no CSS)
✅ Bom P0: "CTA >= 44px hit target" (verificável: width/height computed)
❌ P0 ruim: "design ousado" (não-verificável)
❌ P0 ruim: "boa hierarquia" (subjetivo)

Por que aprender

P0 não-verificável é teatro de qualidade. Modelo "diz que verificou" mas não tem como. P0 verificável = grep ou regex passa ou não. Mensurabilidade => mecanismo.

Conceitos-chave

Verificável = grep/regex: teste mecânico
5-8 P0 por skill: dose certa
Sintático preferido: "no <img src> sem alt"
Visual checks: com Playwright via MCP, viáveis também

🎬 `example_prompt` no frontmatter

UX do picker.

O que é

Frontmatter od.example_prompt aparece como tooltip/preview no picker do OD. Usuário hover na skill e vê: "Faça uma landing pra um curso de cybersegurança". Ajuda decidir se a skill se aplica antes de invocar.

Por que aprender

UX do picker é o que faz skill ser usada ou ignorada. Sem example_prompt, usuário precisa imaginar uso. Com, ele vê. Marketing micro da sua skill.

Conceitos-chave

1 prompt curto: 1 frase
Específico: "para X" > "para qualquer site"
Idiomas múltiplos: array de strings
Atualiza com uso: revise quando o uso evolui

📂 Onde instalar para testar

~/.claude/skills/<nome>/.

O que é

Para teste local, instale em ~/.claude/skills/landing-curso/ (caminho global). Para distribuir num projeto específico, em ./skills/landing-curso/ do repo. Em ambos, daemon escaneia no boot.

Por que aprender

Path errado = skill invisível, parece quebrada. Saber path certo = não perder horas debugando.

Conceitos-chave

~/.claude/skills/: global
./skills/: projeto local
./.claude/skills/: escopo Claude Code
Resolve: projeto > usuário se há conflito

🔄 Restart do daemon e aparição no picker

Hot-reload e cache.

O que é

Skills são escaneadas no boot do daemon. Após adicionar pasta nova:

pnpm tools-dev restart
# ou
pkill -f "od-daemon"
pnpm tools-dev start

Skill aparece no picker após restart. Para hot-reload sem restart: chame POST /api/skills/refresh manualmente.

Por que aprender

Sem restart, mudanças não aparecem. Tempo de feedback alto = ciclo de design lento. Com hot-reload, edição → veja resultado em segundos.

Conceitos-chave

restart cmd: pnpm tools-dev restart
Hot-reload: POST /api/skills/refresh
Cache invalidation: mudou template? cache cai
Logs: pnpm tools-dev logs mostra skills carregadas

🚀 Submeter ao upstream open-design

PR pattern.

O que é

Skill genérica e útil pra outros = pattern de PR pro repo OD upstream:

Fork open-design repo
Adicione pasta em skills/<sua-skill>/
Atualize skills/README.md índice
Adicione 1-2 screenshots de output em docs/screenshots/<sua-skill>/
PR com título "skill: add <name>" e descrição (use case + 1 example output)
Mantainer revisa: P0 são verificáveis? side-files coerentes? compatível com Claude Code puro?

Por que aprender

Skill no upstream = audiência global, atualizações automáticas (outros melhoram), reputação no ecossistema. Caminho de longo prazo.

Conceitos-chave

Fork: use github.com/<your>/open-design
PR template: seguir convenção do repo
Tests opcionais: golden file de output esperado
License: Apache-2.0 = aceita contributions sem CLA

🛠️ Hands-on

Brief: Criar uma skill landing-curso específica para landings de cursos online no estilo INEMA. Tornar default para cenário "education". Testar.

Mkdir: mkdir -p ~/.claude/skills/landing-curso/{assets,references}
SKILL.md: frontmatter completo (name, description, triggers em PT/EN, od.scenario=education, od.default_for=["education"], example_prompt). Body Markdown com workflow em 6 passos.
assets/template.html: :root tokens + comentários de seção (HERO / WHY / CURRICULUM / INSTRUCTOR / PRICING / FAQ / CTA)
references/layouts.md: 5 layouts paste-ready (hero curso, módulos grid, instrutor, pricing edu, FAQ)
references/checklist.md: 6 P0 (CTA "Matricular", price em BRL, mention nível, FAQ acordeão, mobile responsive, no-rounded-buttons)
Restart: pnpm tools-dev restart
Test: brief "landing pra curso de Open Design para devs". Verifique que landing-curso aparece como default no picker.

Verificação rápida

ls ~/.claude/skills/landing-curso/
cat ~/.claude/skills/landing-curso/SKILL.md | head -20
pnpm tools-dev logs --grep "skill loaded"

📚 Fontes

No repositório

docs/skills-protocol.md (322L)
skills/web-prototype/ (referência canônica)
skills/dating-web/ (case complexo)
skills/README.md (índice)

Externas

docs.anthropic.com — Claude Code Skills
github.com/anthropics/awesome-claude-skills

📌 Resumo do Módulo

1. 70% rule: estende quando skill base cobre > 70%; cria nova quando <.

2. Pasta padrão: SKILL.md + assets/template.html + references/{layouts,checklist}.md.

3. Frontmatter: name, description, triggers (multi-idioma), bloco od:.

4. Template HTML com :root tokens + section comments + honest placeholders.

5. layouts.md em paste-ready HTML > descrição em prosa.

6. P0 verificáveis (grep/regex) > subjetivos. 5-8 P0 ideais.

7. example_prompt no frontmatter = tooltip do picker — UX micro.

8. ~/.claude/skills/ global; ./skills/ projeto.

9. Restart daemon ou /api/skills/refresh para hot-reload.

10. PR upstream: fork + skills/<name>/ + screenshot + descrição.

Próximo módulo:

Módulo 3.6 · Daemon, Sidecar IPC →

← Módulo 3.4 Módulo 3.6 →

🎯 Quando criar uma skill nova vs. estender

O que é

Por que aprender

Conceitos-chave

📁 O template de pasta

O que é

Por que aprender

Conceitos-chave

📝 Frontmatter passo a passo

O que é

Por que aprender

Conceitos-chave

🌱 assets/template.html — boas práticas de seed

O que é

Por que aprender

Conceitos-chave

📋 references/layouts.md — paste-ready

O que é

Por que aprender

Conceitos-chave

✅ references/checklist.md — escrevendo P0 que vale

O que é

Por que aprender

Conceitos-chave

🎬 example_prompt no frontmatter

O que é

Por que aprender

Conceitos-chave

📂 Onde instalar para testar

O que é

Por que aprender

Conceitos-chave

🔄 Restart do daemon e aparição no picker

O que é

Por que aprender

Conceitos-chave

🚀 Submeter ao upstream open-design

O que é

Por que aprender

Conceitos-chave

🛠️ Hands-on

📚 Fontes

No repositório

Externas

📌 Resumo do Módulo

🌱 `assets/template.html` — boas práticas de seed

📋 `references/layouts.md` — paste-ready

✅ `references/checklist.md` — escrevendo P0 que vale

🎬 `example_prompt` no frontmatter