# Criar skills do Rakenne com o Skill Workshop

> Guia passo a passo para criar skills de elaboração de documentos personalizadas usando o tipo de projeto Skill Workshop.

Author: map[bio:Founder linkedin:https://www.linkedin.com/in/ricardocabral/ name:Ricardo Cabral]
Published: 2026-02-12

URL: https://rakenne.app/pt/learn/tutorials/creating-skills-with-skill-workshop/index.md


As **skills** do Rakenne são fluxos de elaboração de documentos que o agente pode executar quando os usuários descrevem uma tarefa. O **Skill Workshop** é um tipo de projeto dedicado que permite criar e publicar suas próprias skills em conversa com o agente — sem código. Este tutorial percorre o fluxo completo: da criação de um projeto workshop à publicação de uma skill na biblioteca da sua organização.

## O que você precisa

- Acesso a uma instância Rakenne onde você possa criar projetos.
- Uma ideia clara de um fluxo de domínio que você queira transformar em skill (ex.: "redigir atas a partir de transcrições", "revisar contratos com nosso playbook", "montar checklist de conformidade a partir do regulamento X").

## Passo 1: Criar um projeto Skill Workshop

1. No Rakenne, inicie **Criar projeto** (ou equivalente na sua interface).
2. Ao escolher o tipo de projeto, selecione **Skill Workshop**.
3. Dê um nome ao projeto (ex.: "Minhas skills") e crie-o.

O workspace é provisionado com:

- **Skill skill-creator** — Uma skill integrada em `.pi/skills/skill-creator/` que guia o fluxo de criação.
- **AGENTS.md** — Instruções que informam ao agente que é um workspace de criação de skills e que as skills ficam em `output/`.
- **output/** — Um diretório vazio onde cada skill que você criar ficará (um subdiretório por skill).

Você usa o mesmo workspace que já conhece: chat com o agente, árvore de arquivos, visualização de documentos. A única diferença é o modelo e o objetivo: produzir skills em vez de um único documento.

## Passo 2: Iniciar a conversa de criação

Abra o projeto e, no chat, diga o que você quer construir. Por exemplo:

- *"Quero criar uma skill que transforme transcrições de reuniões em notas estruturadas com decisões e ações."*
- *"Precisamos de uma skill que ajude a redigir avaliações de impacto à privacidade usando nosso template interno e a PIPEDA."*

O agente usará a skill **skill-creator** e **não** criará arquivos até entender seu fluxo. Ele fará perguntas de forma estruturada (fase **Elicit**).

## Passo 3: Responder às perguntas de elicitação

O agente perguntará sobre:

1. **Para que serve o fluxo** — Domínio e tarefa (ex.: atas, revisão de contratos, conformidade).
2. **O que o dispara** — Quando alguém usaria esta skill (ex.: "quando o usuário tem uma transcrição e quer notas estruturadas").
3. **Quais passos estão envolvidos** — A sequência (ex.: receber entrada → extrair decisões e ações → confirmar ambiguidades → produzir documento).
4. **Como é a saída** — Tipo de documento, seções, formato (ex.: resumo executivo, registro de decisões, ações).
5. **Conhecimento de domínio** — Regulamentos, padrões, templates ou material de referência que o agente deve usar.

Responda em linguagem simples. O agente transformará suas respostas em uma skill estruturada; você não precisa saber markdown ou YAML. Se tiver templates ou documentos de referência, pode adicioná-los depois ou descrevê-los para o agente referenciar placeholders.

## Passo 4: Deixar o agente fazer scaffold e escrever a skill

Quando o agente tiver informações suficientes, ele vai:

1. **Escolher um slug** — Um identificador em kebab-case (ex.: `meeting-notes`, `contract-review-playbook`).
2. **Chamar `scaffold_skill`** — Isso cria `output/{slug}/` com um template `SKILL.md` e opcionalmente os diretórios `references/` e `assets/`.
3. **Editar `SKILL.md`** — Preenche os passos do fluxo, links para arquivos de referência e linguagem de gatilho na descrição.
4. **Adicionar arquivos reference e asset** — O conhecimento de domínio vai em `references/`; templates ou exemplos de saída em `assets/`.

Tudo isso acontece no chat; você pode acompanhar a árvore de arquivos e abrir arquivos para revisar. As skills são escritas **apenas** em `output/`.

## Passo 5: Validar e refinar

Antes de considerar a skill pronta, o agente executará **`validate_skill`**. Isso verifica:

- **SKILL.md** existe e tem frontmatter YAML válido (`name`, `description`).
- **Qualidade da descrição** — A descrição inclui linguagem de gatilho (ex.: "Use when…", "Use for…").
- **Tamanho do body** — Body do SKILL.md com menos de 500 linhas (conteúdo longo deve ir em `references/`).
- **Integridade das referências** — Links no SKILL.md apontam para arquivos existentes; sem links quebrados.
- **metadata.json** — Presente e válido (ou aviso se faltar; você adiciona no próximo passo).

Se algo falhar, o agente sugerirá correções (ex.: adicionar linguagem de gatilho, corrigir um caminho, mover conteúdo para arquivo de referência). Você pode refinar no chat e revalidar até todos os checks passarem.

## Passo 6: Preparar metadados para a biblioteca

Quando estiver satisfeito com o conteúdo da skill, o agente **preparará para publicar**:

1. **Executar `preview_metadata`** — Mostra como a skill aparecerá na biblioteca. Se `metadata.json` não existir, um rascunho é gerado a partir do frontmatter do SKILL.md.
2. **Editar `metadata.json`** — Juntos você definirá **title** (nome legível para a biblioteca), **description** (resumo curto), **tags** (substantivos comuns em inglês orientados ao domínio, ex.: "Productivity", "Meetings", "Legal", "Compliance") e **examples** (dois ou três prompts de exemplo).
3. **Validar novamente** — Um último `validate_skill` garante que metadados e estrutura estejam completos.

Depois disso, o agente dirá que a skill está pronta para publicar.

## Passo 7: Publicar na sua biblioteca

1. Na **barra de ferramentas do projeto** clique em **Publish Skill**.
2. Um diálogo lista as skills no seu diretório `output/` (cada pasta que contém um `SKILL.md`). Selecione a skill que deseja publicar.
3. Confirme. O frontend chama a API de publicação; a skill é copiada para a biblioteca de skills da sua organização e registrada no catálogo.
4. Você verá uma mensagem de sucesso (ex.: "Skill publicada na biblioteca"). A skill fica disponível ao instalar skills em qualquer projeto do seu tenant. Republicar o mesmo slug atualiza a skill existente.

## Anatomia de uma skill Rakenne

Uma skill mínima em `output/{slug}/` é composta por:

- **SKILL.md** — Obrigatório. Frontmatter YAML com `name` (slug) e `description` (incluindo linguagem de gatilho). Body: passos do fluxo, regras e links para referências.
- **metadata.json** — Obrigatório para publicar. `title`, `description`, `tags` (array), `examples` (array de prompts de exemplo). Usado pela UI da biblioteca.
- **references/** — Opcional. Arquivos Markdown (ou outros) com conhecimento de domínio; linkados do SKILL.md para o agente poder lê-los durante o fluxo.
- **assets/** — Opcional. Templates ou assets estáticos que o agente usa ao produzir a saída (ex.: `meeting_notes_template.md`).

O fluxo skill-creator mantém o SKILL.md conciso e move o conteúdo detalhado para `references/` para o agente ter um fluxo claro e escaneável mais contexto rico quando necessário.

## Dicas

- **Um fluxo por skill** — Se você tem vários fluxos distintos, crie uma skill por fluxo; pode criar várias skills no mesmo projeto workshop (cada uma em seu `output/{slug}/`).
- **Linguagem de gatilho importa** — O agente usa a `description` da skill para decidir quando ativá-la. Frases como "Use when the user wants to…", "Use for drafting…" ou "Use to generate…" ajudam a casar a intenção.
- **Itere no workshop** — Você pode reabrir o projeto a qualquer momento, editar arquivos ou conversar com o agente para alterar a skill, revalidar e **Publish Skill** de novo para atualizar a cópia na biblioteca.
- **Sem extension.ts para skills de domínio** — O Skill Workshop é para skills baseadas em markdown (SKILL.md + references + assets). Extensões TypeScript estão fora do escopo do fluxo guiado; o skill-creator não cria nem edita `extension.ts`.

## Próximos passos

- Use [Session Management and Context Hygiene](/learn/tutorials/session-management/) para que cada tarefa de criação fique em uma sessão focada.
- Leia [Rakenne 0.2.0 — Skill Workshop e mais](/learn/releases/rakenne-0-2-0/) para o conjunto completo de recursos e melhorias da biblioteca.
- Depois de publicar, instale sua skill em um projeto de elaboração de documentos e execute alguns prompts de exemplo para confirmar o comportamento esperado.


---

Back to [Tutoriais](https://rakenne.app/pt/learn/tutorials/index.md)