CH 14 · Skill e Workflow

Número de palavras~4.740 palavrasTempo~25 minPré-requisitoCH 08, CH 13NívelReproduzível

Objetivo do capítulo

Antes, você tinha que explicar seus requisitos com clareza toda vez que mandava o Agent fazer alguma coisa. Mas algumas tarefas têm passos fixos — como o "resumir um repositório, gerar como documento" que rodamos no CH 05, ou relatórios semanais, organização de dados, tarefas do tipo diário. Ter que repetir o processo do zero toda vez é desperdício demais. Essas tarefas valem a pena virar "uma única folha de instrução": diga ao Agent "quando você encontrar esse tipo de tarefa, siga esse conjunto de passos". Isso é Skill. Este capítulo esclarece o que é a Skill do dsh, de onde ela vem, como o modelo a usa, depois instala uma Skill pronta para uso direto — basta dizer uma palavra ao Agent, e ele instala sozinho — transformando-a no seu "recurso reutilizável" pessoal.

Um fato-chave: Skill também é um plugin

Assim como MCP e subagentes, Skill no dsh não é uma entrada separada; é outra combinação de plugins. Olhando para a árvore de configuração, a família de capacidades de skill é composta por quatro peças:

Plugin	O que faz	Papel
dsh-skill	Registro: mescla diretórios de skill de várias fontes, resolve por nome a "vencedora"	Gerente do armazém
dsh-skill-filesystem	Descobre skills locais em diretórios de projeto e do usuário, monitora mudanças de arquivo	Comprador
dsh-tool-skill	Mostra ao modelo a lista de skills disponíveis, fornece a ferramenta skill de carregamento	Recepção
dsh-skill-badge	Skill de badge oficial que vem junto, desativada por padrão	Decoração

Todos esses quatro vêm instalados por padrão na config web — então dá para usar agora mesmo, nada a instalar. Mais uma vez o "tudo é um plugin" do CH 08: até as "capacidades reutilizáveis" em si são montadas por plugins.

O que é Skill: um "como fazer uma tarefa" escrito

Ferramentas são "ações" que o Agent pode "chamar" (ler/escrever arquivos, pesquisar na web); Skills são "folhas de instrução" escritas para o Agent — um conjunto de instruções específicas da tarefa dizendo "quando você encontrar esse tipo de tarefa, siga esse conjunto de passos".

A maior diferença é reusabilidade: ferramentas são fornecidas pelo sistema, Skills são acumuladas por você. Você descobre uma abordagem útil para uma tarefa, escreve como uma Skill, e daí em diante quando o Agent encontrar o mesmo tipo de tarefa, você não precisa repetir os requisitos. E skills seguem sua localização: colocada no .dsh/skills do projeto é nível-projeto, só vale para aquele projeto; colocada no diretório do usuário ~/.dsh/skills é nível-global, disponível em qualquer projeto — a próxima seção "cinco prateleiras" mostrará a hierarquia completa.

E o "Workflow": uma Skill é o Workflow mais simples

Uma frase para lembrar: uma Skill é o workflow mais simples. A essência de workflow é "solidificar a experiência humana num processo" — e uma Skill é exatamente isso: entrada clara, saída clara, passos fixos, reutilizável individualmente. É um pequeno processo comprimido em uma única tarefa.

A diferença é granularidade. Uma Skill lida com "como fazer uma única tarefa" (uma receita para um prato); Workflow lida com "como encadear múltiplas tarefas em ordem" (a esteira inteira, de comprar legumes, lavar verdura até servir, também gerenciando ramificações, handoffs, quem vai primeiro). No preset Standard do dsh, "Skills" e "Workflows" são duas ferramentas lado a lado — para rotinas fixas de passo único, Skill basta; só para cadeias de múltiplos passos você precisa de Workflow.

Colocando os dois lado a lado, a diferença fica mais clara:

Dimensão	Skill	Workflow
Lida com	Como fazer uma única tarefa	Em que ordem encadear múltiplas tarefas
Granularidade	Rotina fixa de um passo	Pipeline de múltiplos passos
Ramificação & handoff	Não é responsável	Responsável (condições, handoffs, ordem)
Reuso	Reutilizável individualmente	Re-orquestrar conforme necessário
Analogia	Uma receita para um prato	A esteira inteira da compra dos legumes até servir

Então quando você escreve uma Skill para uma única tarefa fixa, você na verdade construiu "o workflow mais simples".

Como é uma Skill

Uma Skill é um arquivo Markdown com frontmatter; a forma padrão é um pacote de diretório: o nome da pasta é o nome da skill, e dentro dela precisa haver SKILL.md — adequado para skills que vêm com recursos acompanhantes (scripts, docs de referência, assets).

O nome deve estar em kebab-case minúsculo (^[a-z0-9]+(?:-[a-z0-9]+)*$), por exemplo code-review, weekly-report.

Um pacote de diretório padrão tem este formato:

code-review/
├── SKILL.md        # Obrigatório: frontmatter + corpo de instruções
├── scripts/        # Opcional: scripts acompanhantes (.py / .sh etc.)
├── references/     # Opcional: docs de referência, templates de checklist de revisão
└── assets/         # Opcional: assets, arquivos de exemplo

SKILL.md é o único arquivo obrigatório; o corpo pode referenciar scripts e docs de referência no pacote por caminhos relativos. A estrutura mínima tem este formato:

---
name: code-review
description: Revisar um trecho de código seguindo um checklist unificado e gerar comentários de revisão estruturados
whenToUse: Quando o usuário pedir "revisão de código"
---

# Code Review

Siga esta ordem:

1. Leia primeiro o README relevante para entender qual problema esse código resolve;
2. Liste as exportações públicas e funções principais, anotando o que cada uma faz;
3. Procure pontos óbvios de risco: tratamento de erro, casos de borda, informações sensíveis;
4. Saída em formato de tabela: Arquivo / Problema / Severidade / Sugestão.

Apenas name e description são obrigatórios no frontmatter; os outros campos são todos opcionais:

Campo	Finalidade
name	Nome único da Skill (kebab-case, obrigatório)
description	Descrição de uma linha; o modelo usa para julgar "essa tarefa é para mim" (obrigatório)
whenToUse	Dica extra de momento de uso (opcional)
disable-model-invocation	Definido como true: só o usuário pode chamar via /name, o modelo não pode auto-carregar (opcional)
user-invocable	Definido como false: só o modelo pode chamar, /name do usuário é inválido (opcional)

Dois switches: quem pode chamar

Dois campos no frontmatter controlam "quem pode chamar":

Combinação	Efeito
Nenhum	Tanto modelo quanto usuário podem chamar (padrão)
disable-model-invocation: true	Só o usuário pode chamar via /name; invisível no diretório do modelo e na ferramenta skill — adequado para fluxos sensíveis ou de alto custo para impedir que o modelo dispare casualmente
user-invocable: false	Só o modelo pode chamar; /name do usuário é inválido
Ambos off	Só código confiável pode chamar; modelo e usuário não conseguem tocar

De onde vêm as Skills: cinco "prateleiras"

Primeiro distinga duas coisas: esta seção é sobre de onde o dsh lê as skills — ou seja, em qual diretório local a skill deve ser colocada para ser descoberta. O dsh usa o plugin dsh-skill-filesystem para escanear vários diretórios raiz em uma ordem fixa e coletar as skills no registro. "Instalar uma nova skill" é outra coisa: vá a um marketplace de skills da comunidade (como o SkillHub da Tencent) ou ao Plugin Market do dsh, e instale o SKILL.md pronto de alguém nesses diretórios de prateleira — a seção "instale uma Skill pronta" abaixo faz exatamente isso.

O dsh-skill-filesystem escaneia vários diretórios raiz em uma ordem fixa, coletando as skills no registro. Quanto mais acima, maior a prioridade — quando aparece uma skill de mesmo nome em várias prateleiras, a que vem antes ganha:

Prioridade	Diretório	Quem coloca aqui
1	<project-root>/.dsh/skills	Acompanha o projeto, distribuído com o repositório
2	<project-root>/.agents/skills	Compatível com outras ferramentas (ex. Claude Code), localização compartilhada
3	Diretórios customizados da config customSkillDirs	Outras localizações especificadas manualmente
4	<dshHome>/skills (~/.dsh/skills)	Nível-usuário, disponível em qualquer workspace
5	<agentsHome>/skills (~/.agents/skills)	Diretório de nível-usuário compartilhado com outras ferramentas Agent

Como o modelo "vê" as Skills

Skills são escritas para o modelo ver; como ele sabe quais existem? Esse mecanismo é fornecido pelo plugin dsh-tool-skill, instalado por padrão na config web (você pode ver em dsh --profile web --dump-config). Ele opera por meio de três mecanismos:

1. Diretório de sessão: antes do início da sessão e da primeira requisição, o modelo recebe uma mensagem persistente listando os nomes e descrições de uma linha de todas as skills disponíveis, e é avisado "antes de agir, carregue primeiro a skill correspondente, não chute a partir do resumo".
2. Ferramenta skill: quando o modelo julga que uma skill é relevante, usa skill({ name }) para carregar o corpo completo de instruções — o corpo retorna como um bloco <skill_content> e permanece no histórico como resultado de ferramenta. A imagem abaixo é uma Trajectory real: o modelo primeiro chama a ferramenta skill para carregar as instruções completas de aihot, depois chama pwsh para executar a requisição de verificação; as duas chamadas de ferramenta ficam cristalinas na Trajectory.

3. Gesto do usuário /name: você digita /code-review direto na caixa de entrada, e as instruções da skill são injetadas na rodada como uma mensagem do usuário, e o modelo simplesmente segue. Observação: esse nome precisa existir de fato nas prateleiras do workspace, e permitir invocação pelo usuário — digitar um nome de skill que não existe é tratado como texto comum e não tem efeito.

Um detalhe: depois da injeção /name do usuário, o modelo não usa a ferramenta skill para carregá-la de novo — evitando que as mesmas instruções sejam enfiadas duas vezes, queimando tokens.

Se você perguntar ao modelo "quais skills você tem agora" e ele não conseguir reportá-las, primeiro confirme se a config web tem o plugin @deepseek-ai/dsh-tool-skill (dá para ver com dsh --profile web --dump-config).

Mãos à obra: instale uma Skill pronta (use como está)

A essência de instalar uma skill pronta é colocar o SKILL.md pronto de alguém no diretório "prateleira" do dsh (geralmente o .dsh/skills do projeto) — a comunidade já tem um grande lote de skills prontas para pegar.

Aqui usamos aihot como exemplo: é uma skill do tipo pesquisa do conhecido bloguer de tech em IA "Digital Life Kazike" (Shuzhi Shengming Kazike), habilidoso em fazer scraping de notícias diárias de IA e tendências da indústria.

Passo 1: diga uma palavra ao Agent, deixe ele instalar para você

Não precisa procurar arquivos e criar diretórios por conta. Volte para a conversa e diga:

Por favor, instale a AIHOT Skill: https://aihot.virxact.com/aihot-skill/README.md Me diga se preciso iniciar uma nova sessão depois da instalação. Se o instalador suportar, por favor anexe: --actor seu-Actor-ID

O ID depois de --actor é atribuído a você após se registrar na plataforma AIHOT, e será escrito no .aihot-actor-id local depois da instalação; o Agent o carrega para identificação ao fazer requisições.

O Agent vai fazer sozinho: ir ao site oficial, baixar o SKILL.md do AIHOT e arquivos acompanhantes, colocá-los na localização padrão de descoberta do DSH (~/.agents/skills/aihot/), fazer verificação de integridade SHA-256 um a um, escrever a config do actor, gerar .gitignore, e reportar o resultado para você. Após a instalação, não precisa iniciar uma nova sessão — já está no diretório <available_skills> da sessão atual, pronto para usar.

Passo 2: peça ao modelo para reportar a nova Skill

Volte para a conversa, pergunte:

Que skills você tem agora? O que a skill aihot faz?

O modelo vai reportar — você escreveu zero linha de código e agora tem uma capacidade reutilizável. Ele também dirá o que essa skill especificamente faz (aihot consulta notícias reais atuais de IA em chinês por meio da API anônima somente-leitura do AIHOT, e não "inventa" notícias a partir da memória de treino).

Passo 3 (opcional): peça ao modelo para usá-la

Basta dizer "use aihot para fazer scraping das notícias de IA de hoje", e o modelo carregará essa skill para fazer scraping. O fluxo de pesquisa refinado de outra pessoa agora virou sua capacidade — isso é "usar como está".

Armadilhas comuns

Armadilha	Como evitar
Esqueceu description	Campo obrigatório faltando, a skill inteira é descartada após aviso
Nível de diretório colocado errado	Apenas <root>/<name>/SKILL.md é reconhecido, um nível, não aninhe mais fundo
Modelo não usa ativamente	Escreva description de forma clara sobre "quando usar" (whenToUse também ajuda); se preocupado mesmo, use /name para injetar direto
Editou o corpo mas o modelo não reage	Edições no corpo não afetam o resumo do diretório; o modelo precisa "recarregar" uma vez; só editar campos de resumo como description reflete imediatamente no diretório

O que você aprendeu neste capítulo

Você passa se conseguir completar os itens abaixo:

• [ ] Dizer que uma Skill é "instruções reutilizáveis escritas para o Agent", e a diferença para uma ferramenta é a reusabilidade
• [ ] Saber que Skill no dsh também é um plugin (registro de skill + descoberta via filesystem + ferramenta consumidora)
• [ ] Saber dizer a estrutura de uma Skill (frontmatter tem name / description obrigatórios, whenToUse opcional)
• [ ] Saber a prioridade das cinco prateleiras (projeto .dsh/skills mais alta, diretório do usuário em seguida, utilizável entre projetos)
• [ ] Ter rodado "dizer uma frase ao Agent → ele instala a skill → modelo reporta → modelo carrega e usa"
• [ ] Distinguir os dois switches disable-model-invocation e user-invocable