Create a reusable skill that teaches Bob Shell a repeatable changelog-entry workflow, then invoke it explicitly and let Bob activate it automatically.

IBM Bob Shell skills are reusable instruction sets, stored in a SKILL.md file, that teach Bob a repeatable workflow. In this tutorial, you build a changelog-entry skill that adds Keep a Changelog entries to CHANGELOG.md, run it explicitly with $changelog-entry, then watch Bob activate it automatically when a prompt matches the skill's description.

Skills save you from retyping the same formatting rules or checklist in every prompt. You define the workflow once, and Bob follows it whenever the skill applies.

Prerequisites

Bob Shell

Install Bob Shell v2.x or later and sign in.

Git

You need Git to clone the example repository.

If you do not already have it, clone the Galaxium Travels demo code.

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

While not required, consider completing Start a project with /init and AGENTS.md and Write effective prompts for Bob Shell first.

Create a changelog-entry skill

Bob Shell loads skills from folders that contain a SKILL.md file. Project skills live in .bob/skills/ in the project root, so Git tracks them alongside the codebase and your team can use them. Global skills live in ~/.bob/skills/ and apply to all your projects.

Create the skill folder

Change to the Galaxium Travels root directory and create a folder for the skill:

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

Write the SKILL.md file

Create .bob/skills/changelog-entry/SKILL.md with the following content. You can use any text editor, or run the command as written:

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.
---

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

The front matter defines two required fields:

name: The skill name. Match it to the folder name, because Bob Shell uses the folder name to reference the skill, for example $changelog-entry.
description: What Bob reads to decide whether the skill applies to a request when you do not reference it by name. If you omit it, Bob uses the first line of the instructions instead, so always write a clear description.

Everything below the closing --- is the set of instructions Bob follows when the skill activates.

Start Bob Shell

Start an interactive session in Agent mode from the Galaxium Travels root directory:

bob chat --mode agent

Agent mode gives Bob the tool access it needs to activate skills and edit files. If Bob Shell asks whether you trust the folder, trust the folder so Bob can load the project's skills.

Invoke the skill directly

Reference the skill by name so you can see the instructions Bob follows.

Edit `README.md`

Ask Bob to make a small, low-risk edit so you have something to log:

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

Bob shows the proposed change as a diff. Select Approve to apply the edit.

Log the change with the skill

Type $ to open the skill picker, then select changelog-entry. Bob Shell inserts the skill reference into your prompt:

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

Bob asks for permission to use the skill and to edit files. Approve each request. Bob loads the changelog-entry skill and creates CHANGELOG.md, because the project has none. Bob then adds an entry similar to the following:

## [Unreleased]

### Added

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

Verify the first changelog entry

Ask Bob to show you the changelog:

Show me @CHANGELOG.md

The entry matches the changelog entry Bob generated in Log the change with the skill.

Let Bob activate the skill automatically

Make a second change and ask Bob to log it without mentioning the skill by name. Bob can recognize from the skill's description that it applies and activate it on its own.

Clear the conversation history

Enter the /clear slash command to reset the conversation history, so Bob has no memory of the previous skill reference:

/clear

Make a second `README.md` edit

Ask Bob to make a second edit:

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

Approve the edit when prompted.

Log the change without naming the skill

Ask Bob to log the change without naming the skill:

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

Bob recognizes that the request matches the changelog-entry skill's description and activates it without a $changelog-entry reference. Approve the skill and file-edit requests when prompted. Bob adds another entry in the same format.

Verify both changelog entries

Ask Bob to show you the changelog:

Show me @CHANGELOG.md

The changelog now contains two entries under ## [Unreleased], similar to the following:

## [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

Manage your skills

Each skill is a folder on disk, so you manage skills with your usual file tools:

List skills: Look in .bob/skills/ for project skills and ~/.bob/skills/ for global skills. If both locations contain a skill with the same name, the project skill takes precedence.

Edit a skill: Edit its SKILL.md file. You can also add supporting files, such as templates or checklists, to the skill folder.

Reference a skill: Type $ or enter /skills in Bob Shell to insert a skill reference into your prompt.

Troubleshooting

The skill does not appear in the `$` picker

Confirm the file path is .bob/skills/changelog-entry/SKILL.md, the front matter includes name and description, and the folder is trusted. For details, refer to Trusted folders. The skill folder name must be lowercase kebab-case, such as changelog-entry. Bob skips folders with invalid names without showing an error. Restart Bob Shell after you add a skill.

Bob does not activate the skill automatically

Bob matches requests against the skill's description. Rephrase the prompt to use words from the description, or reference the skill directly with $changelog-entry.

Next steps

In this tutorial, you learned how skills let you define a workflow once and have Bob apply it consistently. You can reference a skill explicitly with $<skill-name> or let Bob activate it automatically based on its description.

To add templates and supporting files to a skill, refer to Skills.

To build a specialized persona with its own role, instructions, and tool access, refer to Custom modes.

Create and use skills in Bob Shell