Cria uma skill reutilizável que ensina ao Bob Shell um workflow repetível para entradas de changelog e, em seguida, invoca-a explicitamente e deixa o Bob ativá-la automaticamente.

As skills do IBM Bob Shell são conjuntos de instruções reutilizáveis, armazenados num ficheiro SKILL.md, que ensinam ao Bob um workflow repetível. Neste tutorial, constróis uma skill changelog-entry que adiciona entradas Keep a Changelog ao CHANGELOG.md, executa-a explicitamente com $changelog-entry e, em seguida, observas o Bob ativá-la automaticamente quando um prompt corresponde à descrição da skill.

As skills poupam-te de redigitar as mesmas regras de formatação ou checklist em cada prompt. Defines o workflow uma vez e o Bob segue-o sempre que a skill se aplica.

Pré-requisitos

Bob Shell

Instala o Bob Shell v2.x ou posterior e inicia sessão.

Git

Precisas do Git para clonar o repositório de exemplo.

Se ainda não o tens, clona o código demo Galaxium Travels.

git clone https://github.com/IBM/galaxium-travels

Embora não seja obrigatório, considera completar primeiro Iniciar um projeto com /init e AGENTS.md e Escrever prompts eficazes para o Bob Shell.

Criar uma skill changelog-entry

O Bob Shell carrega skills a partir de pastas que contêm um ficheiro SKILL.md. As skills de projeto ficam em .bob/skills/ na raiz do projeto, por isso o Git rastreia-as junto com a base de código e a tua equipa pode usá-las. As skills globais ficam em ~/.bob/skills/ e aplicam-se a todos os teus projetos.

Criar a pasta da skill

Muda para o diretório raiz do Galaxium Travels e cria uma pasta para a skill:

cd galaxium-travels
mkdir -p .bob/skills/changelog-entry

Escrever o ficheiro SKILL.md

Cria .bob/skills/changelog-entry/SKILL.md com o seguinte conteúdo. Podes usar qualquer editor de texto, ou executar o comando tal como está escrito:

cat > .bob/skills/changelog-entry/SKILL.md <<'EOF'
---
name: changelog-entry
description: Adds an entry to CHANGELOG.md using the Keep a Changelog format, creating the file if it does not exist, so change history stays consistent and release-ready.
locale: pt
---

Add an entry to CHANGELOG.md using the Keep a Changelog format (https://keepachangelog.com/).

- If CHANGELOG.md does not exist, create it at the project root with this structure before adding an entry:

  # Changelog

  All notable changes to this project are documented in this file.
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

  ## [Unreleased]

- Add new entries under the `## [Unreleased]` section, under one of these subheadings: `### Added`, `### Changed`, `### Fixed`, `### Removed`. Create the subheading if it is not already present under `## [Unreleased]`.
- Write each entry as a single bullet point in the imperative mood ("Add", not "Added"), starting with a capital letter, with no trailing period.
- Base the entry on the actual diff, not on the wording of the request. Run `git diff` to review what changed before writing the entry.
- Only edit CHANGELOG.md. Do not stage or commit the change.
EOF

O front matter define dois campos obrigatórios:

name: O nome da skill. Deve coincidir com o nome da pasta, porque o Bob Shell usa o nome da pasta para referenciar a skill, por exemplo $changelog-entry.
description: O que o Bob lê para decidir se a skill se aplica a um pedido quando não a referencias pelo nome. Se o omitires, o Bob usa a primeira linha das instruções, por isso escreve sempre uma descrição clara.

Tudo abaixo do --- de fecho é o conjunto de instruções que o Bob segue quando a skill é ativada.

Iniciar o Bob Shell

Inicia uma sessão interativa no modo Agent a partir do diretório raiz do Galaxium Travels:

bob chat --mode agent

O modo Agent dá ao Bob o acesso às ferramentas necessárias para ativar skills e editar ficheiros. Se o Bob Shell perguntar se confias na pasta, confia na pasta para que o Bob possa carregar as skills do projeto.

Invocar a skill diretamente

Referencia a skill pelo nome para poderes ver as instruções que o Bob segue.

Editar `README.md`

Pede ao Bob para fazer uma edição pequena e de baixo risco para teres algo para registar:

Add a one-line note to the end of the README.md that says "Powered by IBM Bob."

O Bob mostra a alteração proposta como um diff. Seleciona Approve para aplicar a edição.

Registar a alteração com a skill

Escreve $ para abrir o seletor de skills e, em seguida, seleciona changelog-entry. O Bob Shell insere a referência da skill no teu prompt:

$changelog-entry Add a changelog entry for this change.

O Bob pede permissão para usar a skill e editar ficheiros. Aprova cada pedido. O Bob carrega a skill changelog-entry e cria CHANGELOG.md, porque o projeto não tem nenhum. Em seguida, o Bob adiciona uma entrada semelhante à seguinte:

## [Unreleased]

### Added

- Add "Powered by IBM Bob." note to the end of README.md

Verificar a primeira entrada do changelog

Pede ao Bob para te mostrar o changelog:

Show me @CHANGELOG.md

A entrada corresponde à entrada do changelog que o Bob gerou em Registar a alteração com a skill.

Deixar o Bob ativar a skill automaticamente

Faz uma segunda alteração e pede ao Bob para a registar sem mencionar a skill pelo nome. O Bob pode reconhecer pela descrição da skill que ela se aplica e ativá-la por conta própria.

Limpar o histórico da conversa

Insere o comando slash /clear para repor o histórico da conversa, para que o Bob não tenha memória da referência anterior da skill:

/clear

Fazer uma segunda edição ao `README.md`

Pede ao Bob para fazer uma segunda edição:

Add a one-line comment above the main heading in README.md that says "Galaxium Travels".

Aprova a edição quando solicitado.

Registar a alteração sem nomear a skill

Pede ao Bob para registar a alteração sem nomear a skill:

Add an entry to CHANGELOG.md in Keep a Changelog format.

O Bob reconhece que o pedido corresponde à descrição da skill changelog-entry e ativa-a sem uma referência $changelog-entry. Aprova os pedidos de skill e de edição de ficheiros quando solicitado. O Bob adiciona outra entrada no mesmo formato.

Verificar ambas as entradas do changelog

Pede ao Bob para te mostrar o changelog:

Show me @CHANGELOG.md

O changelog agora contém duas entradas em ## [Unreleased], semelhantes ao seguinte:

## [Unreleased]

### Added

- Add "Powered by IBM Bob." note to the end of README.md
- Add "Galaxium Travels" comment above the main heading in README.md

Gerir as tuas skills

Cada skill é uma pasta em disco, por isso geres skills com as tuas ferramentas de ficheiros habituais:

Listar skills: Procura em .bob/skills/ para skills de projeto e ~/.bob/skills/ para skills globais. Se ambas as localizações contiverem uma skill com o mesmo nome, a skill do projeto tem precedência.

Editar uma skill: Edita o seu ficheiro SKILL.md. Podes também adicionar ficheiros de suporte, como templates ou checklists, à pasta da skill.

Referenciar uma skill: Escreve $ ou insere /skills no Bob Shell para inserir uma referência de skill no teu prompt.

Resolução de problemas

A skill não aparece no seletor `$`

Confirma que o caminho do ficheiro é .bob/skills/changelog-entry/SKILL.md, o front matter inclui name e description, e a pasta é confiável. Para mais detalhes, consulta Pastas confiáveis. O nome da pasta da skill deve estar em kebab-case em minúsculas, como changelog-entry. O Bob ignora pastas com nomes inválidos sem mostrar um erro. Reinicia o Bob Shell depois de adicionar uma skill.

O Bob não ativa a skill automaticamente

O Bob compara pedidos com a description da skill. Reformula o prompt usando palavras da descrição, ou referencia a skill diretamente com $changelog-entry.

Próximos passos

Neste tutorial, aprendeste como as skills te permitem definir um workflow uma vez e ter o Bob a aplicá-lo de forma consistente. Podes referenciar uma skill explicitamente com $<nome-da-skill> ou deixar o Bob ativá-la automaticamente com base na sua descrição.

Para adicionar templates e ficheiros de suporte a uma skill, consulta Skills.

Para construir uma persona especializada com o seu próprio papel, instruções e acesso a ferramentas, consulta Modos personalizados.

Criar e usar skills no Bob Shell