Criar skills do Rakenne com o Skill Workshop

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 para que cada tarefa de criação fique em uma sessão focada.
• Leia Rakenne 0.2.0 — Skill Workshop e mais 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.