Skip to content
Barry Guides
WIP

This guide is a work in progress. Barry is also a work in progress.

Add instructions and prompts

Use this when a bag needs to tell the agent how to work, not only give it tools: a team convention, a procedure to follow on request, or a fact about the current repository. A bag ships fixed guidance as instruction files, and computes guidance at session start with a prompt contributor. The example is house-style, a bag that holds two instructions plus one contributor.

Before you begin

Section titled “Before you begin”
  • Create a bag. A bag of instructions needs no tools.ts.
  • Pack the bag on the identity whose sessions should get the guidance. A session of an identity gets instructions only from the bags it packs.

Write the instructions

Section titled “Write the instructions”

An instruction is a Markdown file in the bag’s instructions/ directory, with optional front matter. Its mode decides when the text reaches the model:

  • always joins the system prompt of every session. All always-on instructions share a budget of 6,000 characters, so keep them short.
  • on-demand, the default, costs one line: the session’s prompt lists the instruction’s name and description, and the agent reads the body with the get_instructions tool when it needs it. An on-demand instruction needs a description, because that line is all the agent sees.
---
mode: always
---


Write commit subjects in the imperative mood, under 72 characters, with no
trailing period. Explain why in the body, not what; the diff shows what.
---
description: How to write release notes for a tagged release
mode: on-demand
---


Group changes under Added, Changed, Fixed, and Removed. Write each entry for
someone who uses the software, not someone who wrote it, and link the pull
request at the end of the line.

The front matter accepts only name, description, and mode. The name defaults to the filename and must be kebab-case; a description has at most 1,024 characters; the body can’t be empty. To scaffold a file, run barry new instruction release-notes --bag house-style --mode on-demand.

An instruction with the same name in an identity’s own instructions/ directory replaces the bag’s, so a person can override a bag author’s guidance.

Point a trait at an instruction

Section titled “Point a trait at an instruction”

A trait can name instructions, so selecting the trait tells the agent which guidance applies:

name: house-style
description: How this team writes commits and release notes, as instructions and a computed prompt section.


prompts:
  entry: prompt.ts


traits:
  releaser:
    description: Points the agent at the release-notes guidance
    instructions: [release-notes]

The trait names instructions, never prose; the text stays in its file. barry bag check fails a trait that names an instruction with no instructions/<name>.md.

Compute a prompt section

Section titled “Compute a prompt section”

Instruction files are static. For guidance that depends on the session, such as the repository it runs in, declare a prompt contributor with prompts: in bag.yaml and default-export a function wrapped in definePrompt, from @barry-rocks/sdk/tools:

import { existsSync } from "node:fs";
import { join } from "node:path";
import { definePrompt } from "@barry-rocks/sdk/tools";


export default definePrompt(({ cwd }) => {
  if (!existsSync(join(cwd, "CHANGELOG.md"))) return [];
  return [
    {
      text: "## Changelog\n\nThis repository keeps a CHANGELOG.md. Add an entry under Unreleased for every user-facing change.",
    },
  ];
});

The function receives the session’s cwd, and its repo, sessionId, and provider when Barry knows them. It returns a list of { text } sections; an async function returns a promise of one. Read the session’s directory from cwd: the contributor runs in a separate process whose own working directory is the bag’s build directory.

Barry bundles the entry and runs it at session start, for terminal sessions and hosted ones alike, within these limits:

Limit Value
Time for one contributor 1.5 seconds
Time for every contributor, builds included 4 seconds
Text from one bag 9,000 characters
Text from every bag 16,000 characters

A contributor that throws, hangs, exits, or returns anything but { text } sections contributes nothing, Barry logs a warning that names the bag, and the session starts anyway. A section over budget drops whole, and a closing line counts what dropped. Only bags installed from a local directory contribute.

Verify

Section titled “Verify”

Install the bag again, then list the on-demand instructions Barry knows:

Terminal
barry install ~/repos/house-style
bonanza tool instructions search-instructions

The result includes release-notes and its description. To check the always-on instruction and the contributor, start a session in a repository that has a CHANGELOG.md, and ask the agent what it knows about commit messages and the changelog.

If it fails

Section titled “If it fails”
  • An instruction is missing from the search. Its front matter has an unknown key, an on-demand instruction lacks a description, or its body is empty. Barry skips a malformed file and keeps listing the others.
  • The computed section never appears. The contributor took longer than 1.5 seconds, threw, or returned something other than sections. Look for the warning that names house-style where the session started.
  • For anything else, see Troubleshooting.

What’s next

Section titled “What’s next”