Write effective prompts for Bob Shell by adding a role, context, and examples, then refine a vague request into documented Python code with error handling.

IBM Bob Shell produces more accurate code when your prompt names the task, a role, context, and an example. In this tutorial rewrite a vague request into a structured prompt, then compare the results.

Prerequisites

Bob Shell

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

To confirm Bob Shell is installed, open a terminal and check the version:

bob --version

What is a prompt?

A prompt is a question, request, or command that you give Bob to get the output you want. Vague prompts produce vague answers. A good prompt is clear, specific, and provides enough context for Bob to understand what you want.

Prompt components

An effective prompt combines the following components:

Component	Purpose	Example
Instruction	Tells Bob what task to perform. Strong instructions reduce ambiguity.	"Generate a software bill of materials (SBOM) for this API."
Role	Assigns a persona so Bob tailors the response to that perspective.	"You are a senior software engineer with expertise in Python."
Context	Adds background, such as the situation, audience, tone, or constraints.	"The function runs in a production service and must include error handling."
Example	Shows the pattern, format, or style you want Bob to follow.	"Follow the structure of `@src/api/users.py`."
Cue	Leads into the response you want, usually at the end of the prompt.	"Return only the function, starting with `def`."

You can save your prompts as custom slash commands to reuse and share with your team.

What makes a prompt effective?

The following best practices can help you write effective prompts for Bob.

Be specific: The more specific your prompt, the better Bob can understand what you want. Instead of asking "How do I write a Python function?", ask "How do I write a Python function that takes a list of numbers and returns the average?"

Provide context: If your prompt is about a specific project or codebase, provide some context about it. This helps Bob generate a response that is relevant to your situation. Use @ references, such as @src/main.py, to point Bob to specific files.

Break down tasks: As you would when refining a task in your backlog, break down complex tasks into smaller, more manageable steps. This can help Bob generate more accurate and focused responses.

Include examples: If you are adding a new API, direct Bob to review well-written APIs in your codebase to use as examples. You can also include examples in your prompt to show Bob the format or style you want.

Refine a vague prompt

In this section, you write a vague prompt for Bob and review the output. You then refine your prompt based on the best practices to improve the quality of the response.

The goal is to have Bob generate a Python function that prints the current date and time in UTC format. The function should be well documented and include error handling.

Open a terminal and start an interactive session in Agent mode:

bob chat --mode agent

Enter the following prompt:

Write a Python function that prints the date and time.

Bob generates a response, but it may not meet all of your requirements.

from datetime import datetime

def print_datetime():
    now = datetime.now()
    print(now.strftime("%Y-%m-%d %H:%M:%S"))

The function has no error handling and prints local time, not UTC.

Enter /clear to reset the conversation history, so the first response does not influence the next one:

/clear

Refine your prompt with the prompt components:

Role: "You are a senior software engineer with expertise in Python 3."
Instruction: "Write a Python 3 function that prints the current date and time in UTC format."
Context: "The function should be well documented and include error handling."
Example: Point Bob to an authoritative source, such as the Real Python exception handling best practices.

Enter the refined prompt:

You are a senior software engineer with expertise in Python 3. 
Write a Python 3 function that prints the current date and time in UTC format. 
The function should be well documented and include error handling, 
modeled after https://realpython.com/ref/best-practices/exception-handling/.

"""
utc_datetime.py — Utility for printing the current UTC date and time.
"""

from datetime import datetime, timezone

def print_utc_datetime() -> None:
    """Print the current date and time in UTC (ISO 8601 format).

    Retrieves the current moment from the system clock, attaches UTC timezone
    info, formats it as an ISO 8601 string, and writes it to stdout.

    Returns:
        None

    Raises:
        OSError: If the system clock cannot be read (e.g., hardware failure or
            OS-level permission restrictions).
        ValueError: If datetime formatting unexpectedly fails (e.g., year out
            of the supported range).

    Example:
        >>> print_utc_datetime()
        Current UTC date and time: 2025-07-15T13:42:00.123456+00:00
    """
    try:
        now_utc: datetime = datetime.now(tz=timezone.utc)
    except OSError as exc:
        # System clock is unavailable or inaccessible.
        raise OSError("Failed to read the system clock.") from exc

    try:
        formatted: str = now_utc.isoformat()
    except ValueError as exc:
        # Extremely unlikely, but guard against out-of-range datetime values.
        raise ValueError(
            f"Failed to format the datetime object: {now_utc!r}"
        ) from exc

    print(f"Current UTC date and time: {formatted}")


if __name__ == "__main__":
    print_utc_datetime()

The refined prompt produces a function that uses UTC, includes docstrings, and handles exceptions.

IBM SkillsBuild

IBM SkillsBuild is a free online learning platform with courses on writing effective prompts for AI assistants such as Bob.

To learn more about good prompt writing, take the Craft Precise Prompts for AI Models course.

Next steps

In this tutorial, you learned the components of an effective prompt and refined a vague prompt into one that reliably produces the output you want.

Advance to Create and use skills to turn a well-written prompt into a reusable, repeatable workflow that Bob can apply automatically.

Write effective prompts for Bob Shell