Goose instructions

What is Goose instructions?

‍

Goose instructions usually refers to the .goosehints file that Block’s Goose agent reads to load project-level guidance. It gives Goose extra context about your codebase, conventions, and task-specific preferences so it can work more consistently. (block.github.io)

Understanding Goose instructions

‍

In practice, a .goosehints file is a lightweight way to persist instructions that would otherwise need to be repeated in chat. Goose supports both global and local hint files, and local hints can be placed at the project root or deeper in a directory tree so the agent can pick up more specific guidance as it moves through a repo. (block.github.io)

This makes Goose better suited to long-running coding workflows, especially in larger codebases where standards differ by module. Teams use it to encode build steps, testing expectations, naming conventions, and any background context the agent should remember while editing files or planning changes. Key aspects of Goose instructions include:

1. Project context: It tells Goose what the repository is, how it is structured, and what matters most.
2. Persistent guidance: It stores instructions that should apply across sessions, not just one prompt.
3. Scoped rules: You can keep root-level guidance broad and add narrower hints in subdirectories.
4. Agent alignment: It helps the agent produce outputs that match team conventions and workflow norms.
5. Reusable setup: It reduces repeated prompting for common tasks and preferences.

Advantages of Goose instructions

‍

1. Less repetition: You do not need to restate the same project rules in every session.
2. Better consistency: The agent is more likely to follow the same standards across tasks.
3. Cleaner collaboration: Shared instructions help teams keep one source of truth for agent behavior.
4. More context-aware output: Goose can respond with code and changes that fit the repo’s conventions.
5. Flexible scope: You can tune guidance for the whole project or for a single folder.

Challenges in Goose instructions

‍

1. Keeping it current: Instructions can drift if the codebase or process changes.
2. Too much detail: Overloaded hint files can become noisy or harder for the agent to use well.
3. Scope management: Teams need to decide what belongs globally versus locally.
4. Conflicting guidance: Multiple hint files can create ambiguity if they disagree.
5. Governance: Someone still has to own review, updates, and hygiene.

Example of Goose instructions in action

‍

Scenario: A team has a monorepo with shared utilities, a React frontend, and a Python backend. They add a root .goosehints file for repo-wide rules like testing and commit style, then add deeper hint files for frontend and backend conventions.

When Goose edits a UI component, it follows the frontend hints for styling and component structure. When it touches an API route, it picks up the backend hints instead. The result is a single agent workflow that still respects local conventions without constant manual reminders.

How PromptLayer helps with Goose instructions

‍

PromptLayer helps teams manage the prompts and instructions that sit around agent workflows, so you can version guidance, review changes, and track how instruction updates affect outputs. That makes it easier to treat agent guidance as a shared, testable asset instead of a one-off prompt.

Ready to try it yourself? Sign up for PromptLayer and start managing your prompts in minutes.