@elven-observability/proposals-skill

v0.1.0

Published

4 days ago

Anthropic skill-creator pack codifying Elven Works commercial proposal standards: A4-portrait hybrid .docx generation (locked cover/diagrams + native editable body), canonical 'observabilidade' template, binary lint. Sibling of @elven-observability/docs-s

0High
0Medium
0Low

elven_observability

claude-code anthropic skill proposal proposta docx elven elven-observability pt-br commercial a4

`@elven-observability/proposals-skill`

Propostas comerciais da Elven Works, sempre no mesmo padrão — em .docx A4.

Um pacote npm que instala um skill no Claude Code. Depois de instalado, qualquer pessoa do comercial (ou o agente de IA) gera uma proposta comercial A4 retrato com identidade visual idêntica, valores conferidos, e um .docx editável pronto para enviar — com 3 comandos.

Skill irmã de @elven-observability/docs-skill (documentação técnica) e @elven-observability/decks-skill (apresentações 16:9). Este aqui faz propostas comerciais.

Índice

Comece em 60 segundos

# 1. Instala (uma vez por máquina)
npm install -g @elven-observability/proposals-skill
proposals-skill install

# 2. Cria uma proposta nova
proposals-skill new hinode
cd hinode

# 3. Edita o vars.json, depois:
proposals-skill lint hinode      # 9/9 obrigatório
proposals-skill build hinode     # gera o .docx A4

Pronto. Você tem um .docx A4 retrato no padrão Elven — capa, 18 seções, tabelas de valores, header e footer — pronto para o comercial revisar e enviar.

Por que esse skill existe

Antes: cada proposta saía de um jeito. Página em US Letter em vez de A4, fontes misturadas (Inter + Arial + Times), placeholders {{cloud_destino}} vazando no texto, capa com faixa branca. O cliente recebia documentos que não pareciam da mesma empresa.

Depois: um padrão, codificado em código.

A página (A4 retrato), as fontes (Inter), as cores e os estilos vêm de um contrato único e travado (docx-styles.js).
O conteúdo é template + variáveis: 18 seções canônicas em content.md, preenchidas por um vars.json por cliente.
O .docx é híbrido: capa e diagramas como imagem travada (visual impecável); corpo e tabelas de valores como Word nativo editável.
Um lint binário reprova antes de chegar ao cliente: A4 errado, {{slot}} vazando, valor faltando, fonte fora do padrão.

Resultado: qualquer pessoa do comercial produz proposta com a mesma qualidade.

Instalação

Sem instalar global — npx

npx @elven-observability/proposals-skill install

Requisitos

Node.js 18+
O primeiro npm install baixa o Chromium do Puppeteer (~200 MB) — usado para renderizar a capa.

Sua primeira proposta, passo a passo

1. Crie a pasta

proposals-skill new hinode

hinode é o slug do cliente — kebab-case, sem acento. Você recebe:

hinode/
├── vars.json       ← variáveis do cliente (edite este)
├── content.md      ← conteúdo (cópia editável; em geral não mexa)
└── assets/         ← coloque architecture.png aqui

2. Preencha o `vars.json`

Cliente, projeto, datas, o cenario (3 parágrafos), regiões, e os valores comerciais (migração, SRE, Command Center, total). Schema completo abaixo.

3. Adicione o diagrama de arquitetura

Coloque hinode/assets/architecture.png — o diagrama da migração desse cliente. Sem ele, o build usa um exemplo.

4. Lint

proposals-skill lint hinode

Saída esperada: PASS hinode (9/9). Se reprovar, a mensagem diz a regra (L1–L10) e o motivo. Conserte e rode de novo.

5. Build

proposals-skill build hinode

Gera hinode/hinode-18-05-2026.docx + hinode/source-notes.md (trilha de auditoria com os valores comerciais).

6. Confira e entregue

Abra o .docx no Word. Bata o checklists/pre-deliver.md. Envie.

O documento gerado

.docx A4 retrato, híbrido:

| Camada | Como | Por quê | |---|---|---| | Capa | imagem full-bleed (gradiente Elven + texto) | visual travado, impecável | | Diagramas | imagens fixas embutidas | visual complexo travado | | Corpo (texto, seções) | Word nativo, estilos nomeados | o comercial edita | | Tabelas de valores | tabelas Word nativas | o comercial edita os números | | Header / footer | "Proposta Elven" + "Confidencial — válido por N dias" + página | padrão do documento |

O `vars.json`

| Campo | Tipo | Descrição | |---|---|---| | cliente | string | nome do cliente | | cliente_slug | string | kebab-case sem acento — nomeia pasta/arquivo | | projeto | string | título do projeto | | versao | string | ex: V1 | | data_emissao | string | formato DD.MM.AAAA | | validade_dias | number | validade da proposta | | cenario | string[] | 3 parágrafos sobre o cliente | | cloud_destino | string | nuvem destino | | regiao_primaria / regiao_dr | string | regiões | | aplicacoes_especificas | string[] | apps específicas do cliente | | migracao.horas / migracao.valor_total | number / string | projeto de migração | | sre.horas_mes / sre.valor_mes | number / string | Suporte SRE | | command_center.plano / .acionamentos / .valor_mes | string / number / string | Command Center | | total_mensal | string | total SRE + CC | | executivo_elven / responsavel_legal_elven | string | partes Elven | | contato_cliente_nome / responsavel_legal_cliente | string | partes do cliente (opcional) |

Detalhes em skill/reference/vars-schema.md (após install).

As 18 seções

Capa · Cenário · Sobre a Elven · Nossas Soluções · Arquitetura Zero-Trust · Migração · Suporte pós-migração · Treinamento · Sustentação com evoluções · Analytics + planos Command Center · Excedentes · Suporte SRE (escopo + SLA) · Tecnologias Suportadas · Gestão e relatórios · Nossos clientes · Investimento (migração) · Investimento (SRE + CC) · De Acordo.

A maioria é conteúdo fixo da marca; o que muda é preenchido pelo vars.json. Contrato completo em skill/reference/content-contract.md.

Todos os comandos

proposals-skill install [--force]      # copia o skill p/ ~/.claude/skills/
proposals-skill update                 # atualiza o skill instalado
proposals-skill new <cliente-slug>     # cria a pasta da proposta
proposals-skill build <pasta>          # gera o .docx A4 + source-notes.md
proposals-skill lint <pasta>           # lint binário (10 regras)
proposals-skill --version | --help

Lint binário

10 regras. Ou passa, ou reprova.

| Regra | Verifica | |---|---| | L1 | vars.json presente e JSON válido | | L2 | Campos obrigatórios preenchidos | | L3 | Nenhum {{slot}} vazando | | L4 | Tipos corretos (validade numérica, valores string) | | L5 | cliente_slug kebab-case | | L6 | 18 seções canônicas presentes | | L7 | Diagramas existem | | L8 | Sem emoji | | L9 | Data DD.MM.AAAA | | L10 | docx A4 + fonte única (pós-build) |

Perguntas frequentes

O docx saiu em US Letter / com fonte errada. Não sai — o gerador trava A4 e Inter por contrato. Era exatamente esse o bug do sistema antigo (pandoc sem reference-doc). Se viu isso, não foi este skill.

Posso mudar o texto de uma seção fixa? Edite o content.md da pasta do cliente (override) só se houver variação real de escopo. As seções fixas são o discurso comercial padrão — alterá-las por cliente quebra a padronização.

Como gero o PDF? v0.1 entrega .docx. PDF é v0.2 (precisa LibreOffice/Word para converter). Por ora: abra o .docx e exporte como PDF pelo Word.

{{slot}} apareceu no documento. Não deveria — o lint (L3) reprova isso antes do build. Rode proposals-skill lint e preencha o campo faltante no vars.json.

Preciso de um relatório técnico, não proposta. Use @elven-observability/docs-skill. Para slides, decks-skill.

Skills irmãs

| Skill | Faz | Saída | |---|---|---| | docs-skill | documentação técnica + PS reports | .md + PDF | | decks-skill | apresentações / decks | HTML 16:9 + PDF | | proposals-skill | propostas comerciais | .docx A4 |

Três skills, escopos próprios, convenções idênticas — quem usa uma sabe usar as três.

Contribuindo

Bem-vindo: fixtures de teste, mensagens de lint mais claras, correção de bugs de layout.

Não bem-vindo (abra issue antes): segundo template sem caso real, afrouxar regras de lint, mudar o contrato visual (A4, Inter, paleta), novas dependências no CLU.

Fluxo: fork → branch → npm test passando → atualizar CHANGELOG.md → PR. Versionamento SemVer.