Módulo 1.4 · Skills (SKILL.md)

📜 Convenção SKILL.md do Claude Code

O frontmatter mínimo: name, description, triggers.

O que é

SKILL.md é um arquivo Markdown com frontmatter YAML mais corpo. O frontmatter mínimo (compatível com Claude Code) tem:

---
name: web-prototype
description: Gera um protótipo web rodável (single-file HTML)
triggers:
  - "fazer um site"
  - "landing"
  - "prototype"
---

# Workflow

1. Leia template.html primeiro
2. ...

Por que aprender

Esse formato é a fronteira de portabilidade: uma skill bem escrita roda no Claude Code e no OD sem mudança. Esse contrato evita lock-in. Saber escrever um SKILL.md mínimo = poder distribuir suas próprias skills.

Conceitos-chave

name: kebab-case, único por escopo
description: 1 linha — usada no picker
triggers: array de palavras/frases que ativam matching
Body: Markdown puro com workflow e diretrizes
Sem código executável: SKILL.md é declarativo, não script

📁 Anatomia: `assets/` + `references/`

O que vai em cada pasta auxiliar.

O que é

Uma skill séria não é só SKILL.md — é uma pasta:

skills/saas-landing/
├── SKILL.md                  # frontmatter + workflow
├── assets/
│   └── template.html         # HTML seed que o agente abre primeiro
└── references/
    ├── layouts.md            # 8 layouts paste-ready
    ├── components.md         # botão, card, hero variants
    └── checklist.md          # P0/P1/P2 gate

Por que aprender

Assets = seed. O agente sempre abre o template antes de escrever — economiza ~30% de tokens e evita "improviso de estrutura". References = vocabulário. Quando o agente precisa de um padrão, ele consulta em vez de inventar. Quem ignora essa separação acaba com SKILL.md de 800 linhas que o modelo não consegue manter coerente.

Conceitos-chave

assets/: arquivos "seed" — template HTML, frames, imagens placeholder
references/: Markdown auxiliar — layouts, componentes, checklist
Pre-flight reading: daemon injeta assets no contexto antes do prompt do usuário
Tamanho razoável: SKILL.md ~150 linhas, references ~100 cada

🔌 Extensão `od:` no frontmatter

Mode, platform, scenario, preview, design_system, default_for, featured.

O que é

O OD adiciona um bloco opcional od: ao frontmatter — invisível para o Claude Code (ignorado por desconhecimento), rico para o picker do OD:

---
name: saas-landing
description: Landing page para SaaS B2B
triggers: ["landing", "site institucional"]
od:
  mode: prototype
  platform: web
  scenario: marketing
  preview: { aspect: "16:9" }
  design_system: linear-app
  default_for: ["b2b-saas", "fintech"]
  featured: true
---

Por que aprender

A extensão od: é o que diferencia "uma skill" de "uma skill descobrível e configurada". O picker filtra por scenario, sugere design_system default, exibe featured primeiro. Sem essa metadata, o usuário tem que escolher tudo manualmente toda vez.

Conceitos-chave

mode: prototype | deck | scenario
platform: web | mobile | desktop
scenario: marketing | dashboard | onboarding | etc.
design_system: default emparelhado para esse tipo
default_for: categorias onde essa skill é a primeira sugerida
featured: aparece em destaque no picker
Compatibilidade: Claude Code ignora od:, segue funcionando

📦 As 31 skills da box

Taxonomia: prototype × deck × scenario.

O que é

O OD vem com 31 skills curadas, agrupadas em três famílias:

Prototype

web-prototype, saas-landing, mobile-app, dashboard, social-carousel...

Deck

guizang-ppt, pitch-deck, keynote, sales-deck...

Scenario

critique, tweaks, brand-extract, onboarding-flow, dating-web...

Por que aprender

Saber o que existe = não reinventar. Antes de criar uma skill nova, cheque o catálogo: provavelmente já existe uma "70% pronta" que você estende com seu DESIGN.md em vez de fazer SKILL.md do zero.

Conceitos-chave

Prototype: output rodável (single-file HTML, multi-tela, gallery)
Deck: output paginado, magazine-style, exportável a PDF
Scenario: cumpre função (audita, refina, extrai) — não gera artefato novo
Top 5 mais usadas: web-prototype, saas-landing, guizang-ppt, mobile-app, critique

📑 Pre-flight reading enforcement

Por que o agente lê template.html antes de escrever CSS.

O que é

Toda SKILL.md séria tem como primeira instrução: "Antes de qualquer pixel, leia assets/template.html e references/checklist.md". O daemon faz enforcement: injeta o conteúdo desses arquivos no system prompt antes do agente começar. Não é confiança no modelo — é checklist mecânico.

Por que aprender

Modelos LLM falham em "abrir arquivo X" cerca de 30% do tempo. Pre-flight elimina essa fonte de erros: o conteúdo já está no contexto, o modelo não precisa lembrar. Saber isso = saber por que o OD entrega artefatos consistentes onde "AI freestyle" não.

Conceitos-chave

Daemon-side injection: daemon lê e injeta antes do agente
Token budget: ~8k tokens por skill (cuidado com side-files gigantes)
Cache invalidation: editou template? cache invalida na próxima sessão
Skill mal-escrita: sem instrução de pre-flight reading, agente improvisa

🤝 Promessa de compatibilidade

Skill OD roda em Claude Code puro, e vice-versa.

O que é

Uma skill OD respeita a convenção Claude Code: frontmatter base + body Markdown. Tudo o que é OD-específico vive em od: (ignorado por outros runtimes). Isso significa que: você baixa uma skill da galeria do Claude Code, joga em ~/.claude/skills/, e o OD reconhece e usa. E vice-versa: você cria uma skill no OD com od: rica, ela continua funcionando no Claude Code (sem o picker rico).

Por que aprender

É a aposta-base do OD. Sem essa compatibilidade, o ecossistema fragmenta. Time que adota OD pode usar skills da comunidade Claude Code; time que adota Claude Code pode usar skills da comunidade OD. Convergência = ecossistema vivo.

Conceitos-chave

Frontmatter base: name + description + triggers — funcionam em ambos
od: bloco: rico no OD, ignorado em outros runtimes
Sem dependências runtime: SKILL.md é texto estático
Versionamento: Git-friendly, fácil de reviewar em PR
awesome-claude-skills: ecossistema convergente

🗂️ Onde skills moram

Os 3 escopos escaneados no boot.

O que é

No boot, o daemon escaneia 3 diretórios em ordem:

~/.claude/skills/ — skills globais do usuário (compartilhadas com Claude Code)
./skills/ — skills do projeto atual
./.claude/skills/ — skills do projeto, escopo Claude Code padrão

Conflito de nome? Mais específico ganha (projeto > usuário).

Por que aprender

Saber onde colocar suas skills muda comportamento. Skill genérica (deck padrão) → ~/.claude/skills/. Skill específica do cliente (landing-cliente-X com brand específico) → ./skills/ do repo do cliente. Sem essa disciplina, vira "tenho 50 skills no global e nunca sei qual é qual".

Conceitos-chave

~/.claude/skills/: globais, persistem entre projetos
./skills/: projeto-específico, commitadas no repo
./.claude/skills/: escopo Claude Code (sinônimo do anterior)
Boot scan: daemon faz fs.readdir nos 3 paths
Hot-reload: editou skill? próxima sessão lê novo conteúdo

🛠️ Hands-on

Crie sua primeira skill mínima — vale como exercício mesmo sem o OD instalado:

Estrutura: mkdir -p ~/.claude/skills/post-linkedin/{assets,references}
SKILL.md: escreva frontmatter (name, description, triggers, od:) + workflow em 5 passos
template.html: em assets/, escreva o HTML de um card 1080×1080 com tokens em :root
checklist.md: em references/, liste 5 P0 (ex: "fonte display ≠ body", "1 cor de marca")
Teste: reinicie o Claude Code/OD daemon e verifique se aparece no picker

Listagem das skills atuais

ls ~/.claude/skills/
ls ./skills/ 2>/dev/null
find . -name "SKILL.md" -not -path "*/node_modules/*"

📚 Fontes

No repositório

docs/skills-protocol.md (322L)
skills/web-prototype/SKILL.md — referência canônica
skills/guizang-ppt/SKILL.md — deck framework
apps/daemon/src/skills.ts — scanner

Externas

docs.anthropic.com — Claude Code Skills
github.com/anthropics/awesome-claude-skills
guizang-ppt-skill (deck framework)

📌 Resumo do Módulo

1. SKILL.md = frontmatter (name, description, triggers) + body Markdown — convenção Claude Code.

2. Pasta com assets/ (seed) e references/ (vocabulário) é o que faz a skill confiável.

3. Bloco od: adiciona mode, platform, scenario, design_system, default_for, featured.

4. 31 skills box organizadas em prototype × deck × scenario.

5. Pre-flight reading: daemon injeta side-files antes do agente — checklist mecânico.

6. Compatibilidade: skill OD roda em Claude Code, e vice-versa — sem fragmentação.

7. Skills moram em ~/.claude/skills, ./skills, ./.claude/skills — projeto > usuário em conflito.

Próximo módulo:

Módulo 1.5 · Design Systems (DESIGN.md) →

← Módulo 1.3 Módulo 1.5 →

📜 Convenção SKILL.md do Claude Code

O que é

Por que aprender

Conceitos-chave

📁 Anatomia: assets/ + references/

O que é

Por que aprender

Conceitos-chave

🔌 Extensão od: no frontmatter

O que é

Por que aprender

Conceitos-chave

📦 As 31 skills da box

O que é

Por que aprender

Conceitos-chave

📑 Pre-flight reading enforcement

O que é

Por que aprender

Conceitos-chave

🤝 Promessa de compatibilidade

O que é

Por que aprender

Conceitos-chave

🗂️ Onde skills moram

O que é

Por que aprender

Conceitos-chave

🛠️ Hands-on

📚 Fontes

No repositório

Externas

📌 Resumo do Módulo

📁 Anatomia: `assets/` + `references/`

🔌 Extensão `od:` no frontmatter