Goose and AGENTS.md: Hierarchical Context Loading (2026)

In December 2025, the Linux Foundation announced the Agentic AI Foundation, and named three founding project contributions: Anthropic’s Model Context Protocol, OpenAI’s AGENTS.md — and Block’s Goose. Two standards and one agent, donated together. That’s a reasonable moment to ask whether Goose actually reads the standard it was donated alongside, and the answer is a documented yes, with a mechanism that’s more granular than most tools’ single-root-file approach.

AGENTS.md is a Markdown file that AI coding agents read for project-specific instructions — build commands, conventions, and context a human-facing README doesn’t need to carry. Goose’s own docs are explicit: “By default, goose looks for both AGENTS.md and .goosehints at each level.” .goosehints is Goose’s own, older convention for the same purpose; as of the current docs, neither file is deprecated in favor of the other — Goose checks for both, everywhere it checks.

Global and Local Hints

Two scopes, both automatic:

• Global: ~/.config/goose/.goosehints — applies to every Goose session regardless of what directory you’re working in.
• Local: .goosehints (or AGENTS.md) at the project root, and optionally in any directory in the hierarchy below it.

When both exist and disagree, Goose’s docs are direct about the outcome: “If the instructions in your local hints file conflict with your global preferences, goose will prioritize the local hints.” The more specific, project-level file wins.

Loading Is Hierarchical, Not Just Root-and-Home

This is the part that separates Goose’s model from a typical single-root-file setup. Per Goose’s docs: “goose loads hints at the start of your session. As it accesses files in nested directories, it also loads the hint files for those directories.” Multiple hint files in the same hierarchy don’t override each other one-for-one — they combine “in order from root to deepest directory level,” and once a nested file has loaded, it stays active for the rest of the session rather than dropping out of context when Goose moves on to a different file.

Practically: a root AGENTS.md with project-wide conventions, plus a backend/AGENTS.md with API-specific rules, plus a backend/payments/.goosehints with rules specific to the payments module — all three can be active simultaneously once Goose has touched a file in backend/payments/, without the deeper files silently replacing the shallower ones. That’s closer to Claude Code’s nested-CLAUDE.md behavior than to a tool that only reads one file at session start and never revisits the question.

Two Reference Syntaxes Inside a Hints File

Goose’s docs describe two ways to point at other files from within a .goosehints or AGENTS.md:

• @filename.md — automatically pulls that file’s content into immediate context. Use this for something Goose needs on every relevant task.
• Plain reference (mentioning a filename without @) — tells Goose the file exists and is worth reviewing when needed, without forcing it into context up front. Better for large or situational files you don’t want loaded on every session.

# .goosehints

## Testing
See @docs/testing-conventions.md for required test patterns.

## Architecture
Review docs/architecture-decisions/ before touching the payments module —
large file set, load only if you're working in that area.

Customizing Which Filenames Goose Looks For

The default filename list — ["AGENTS.md", ".goosehints"] — isn’t hardcoded. Goose’s docs describe a CONTEXT_FILE_NAMES environment variable that overrides it, letting a team standardize on a different filename (or add one) without changing Goose’s core behavior. If your team already has a CONVENTIONS.md from another tool and doesn’t want a third file, this is the setting that lets Goose pick it up instead of requiring a rename.

Content Guidance, Scoped by Level

Goose’s docs recommend keeping each hints file scoped to its own level rather than repeating project-wide rules at every directory: root-level files should hold project-wide standards, build processes, and general guidelines; module- or feature-level files should add only what’s specific to that area of the codebase. Combined with the hierarchical loading behavior above, that keeps a deeply nested file short — it’s additive context, not a restatement of everything above it.

What This Isn’t: Goose’s Other Config Files

Worth separating clearly, since it’s an easy mix-up: Goose also has a set of YAML configuration files — config.yaml (provider, model, extensions), permission.yaml (tool permission levels), secrets.yaml (API keys), and a tool_permissions.json for runtime permission decisions. None of these carry project instructions or coding conventions — they configure Goose itself (which model, which extensions, what it’s allowed to run). AGENTS.md and .goosehints are the only files in Goose’s system that carry the kind of project-specific guidance this article is about.

FAQ

Q1. Does Goose support AGENTS.md, or only its own .goosehints format? Both. Goose’s docs state it looks for AGENTS.md and .goosehints at each directory level by default — an existing AGENTS.md written for another tool works in Goose without renaming it.

Q2. How is Goose’s hint-loading different from a single-root AGENTS.md tool? Goose loads hierarchically: it starts with hints from the working directory and its parents, then loads additional hint files from nested directories as it accesses files inside them during the session — all staying active simultaneously rather than one replacing another.

Q3. What happens if my global .goosehints and a project’s local file conflict? Local wins. Goose’s docs state it will prioritize the local hints file over global preferences when the two conflict.

Q4. Can I make Goose look for a different filename than AGENTS.md or .goosehints? Yes, via the CONTEXT_FILE_NAMES environment variable, which overrides the default list of ["AGENTS.md", ".goosehints"].

Q5. What’s the difference between @filename and a plain filename reference inside a Goose hints file? @filename.md automatically loads that file’s content into context immediately. A plain reference (no @) tells Goose the file exists and is worth checking when relevant, without forcing it into context up front — intended for large or situational files.

Q6. Does Goose’s config.yaml count as an AGENTS.md-equivalent file? No. config.yaml, permission.yaml, and secrets.yaml configure Goose’s own behavior — model, extensions, permissions — not project coding conventions. Project-level guidance belongs in AGENTS.md or .goosehints.

Related Reading on The Prompt Shelf

• Amp’s AGENTS.md Discovery: The System-Wide Paths (2026)
• How Factory Droid CLI Discovers AGENTS.md (2026)
• Does Claude Code Support AGENTS.md? The Complete 2026 Reference
• AGENTS.md Not Loading? How to Debug It in 2026
• Continue.dev and AGENTS.md: Configuration Guide (2026)

Extensions Need Credentials Too — Keep Them Out of config.yaml

Goose’s secrets.yaml is file-based storage for API keys, which means those keys live on disk in plaintext unless you’re careful about how the file is created and shared. 1Password CLI’s op run injects secrets into the environment at runtime instead, so your MCP extensions and provider connections authenticate without a secrets.yaml file that has to be excluded from every backup, dotfiles repo, or screen-share.