OpenHands reads AGENTS.md from your repository root and injects the full file into a <REPO_CONTEXT> block on every turn — that part is standard. What’s less standard, and the reason this is worth a dedicated writeup, is that OpenHands’s own SDK documentation files AGENTS.md under a section literally titled “Legacy Context,” right next to repo.md, and points toward a newer, separate system — SKILL.md — as where new work should go.
OpenHands (built by All Hands AI, MIT-licensed, formerly OpenDevin) is a model-agnostic, open-source coding agent: point it at a repo, hand it a task, and it edits files, runs commands, and opens PRs, either self-hosted or through OpenHands Cloud. It’s also one of the more interesting cases in the AGENTS.md ecosystem right now, because it’s mid-migration between three overlapping systems, and its docs are unusually candid about which one is being deprecated.
AGENTS.md and repo.md: Full Context, Every Turn
Per OpenHands’s SDK guide, AGENTS.md at the repo root is auto-discovered by load_project_skills(). Its full content lands in <REPO_CONTEXT> in the initial system prompt and — this is the part worth underlining — stays in context for every subsequent turn, not just the first one. The docs describe this as the place for “permanent repository rules and coding standards”: build commands, architectural constraints, things that apply no matter what the agent is doing.
repo.md is documented as the same behavior under a different (older) filename — a holdover from before AGENTS.md existed as a cross-tool convention. If your repo has both, OpenHands doesn’t treat them as competing; repo.md is presented purely as a legacy alias for the same auto-loaded, always-on context slot.
Neither file supports scoping. There’s no per-directory AGENTS.md precedence documented the way Codex or Amp handle it — one file, root only, loaded whole, every turn.
Why OpenHands Calls This “Legacy”
Here’s the detail that makes OpenHands different from most tools in this space: its own SDK documentation groups AGENTS.md and repo.md together under “Legacy Context,” as a category distinct from the newer skills system. That’s not a deprecation notice — AGENTS.md is still auto-loaded and still works exactly as described above — but it signals where the project is putting its design effort going forward. The stated tradeoff is direct: AGENTS.md content “consumes tokens on every LLM turn,” while the newer system is built specifically to avoid that.
This lines up with something separately documented for the OpenHands frontend repo itself: its own AGENTS.md mentions “skills catalog loading” as an architectural concern the project has had to design around — public skills are compiled into the app from an @openhands/extensions package at build time, and a SkillsService merges those with user- and project-level skills at runtime. OpenHands isn’t just recommending the new system to users; its own codebase is built around it.
What Replaced Microagents: .agents/skills/ and SKILL.md
The older “microagents” system lived at .openhands/microagents/, with a repo.md-style general file plus keyword-triggered microagent files alongside it. OpenHands’s own docs now describe that path as the V0 (legacy) location, with repository-specific skills moving to .agents/skills/ in V1 — following the Agent Skills open standard Anthropic published in December 2025, rather than a bespoke OpenHands format.
Each skill is a directory, not a single file:
my-skill/
├── SKILL.md # required — frontmatter + instructions
├── scripts/ # optional — executable code
├── references/ # optional — docs loaded on demand
└── assets/ # optional — templates, static filesThe frontmatter follows the open spec, plus two OpenHands-specific extensions:
| Field | Required | Purpose |
|---|---|---|
name | Yes | Skill identifier — lowercase, hyphens, must match the parent directory name |
description | Yes | What the skill does and when to use it — this is what the agent sees before deciding to load the rest |
triggers | No (OpenHands extension) | Keywords that auto-inject the skill when they appear in the conversation |
paths | No (OpenHands extension, mutually exclusive with triggers) | Glob patterns that inject the skill when the agent touches a matching file |
license, compatibility, metadata | No | Standard Agent Skills fields — environment requirements, attribution, arbitrary key-value pairs |
A real one, adapted from a pattern OpenHands documents for enforcing PR review behavior:
---
name: pr-review-guard
description: >
Ensures every pull request gets an explicit APPROVE or COMMENT review
instead of finishing silently with no review submitted.
triggers:
- pull request
- PR review
- merge
---
# PR Review Guard
Before considering a task complete if it touches a pull request:
1. Confirm a review was actually submitted — either APPROVE or COMMENT,
never left blank.
2. If CI is still running, say so explicitly rather than merging early.
3. Reference the linked issue number in the PR body if one exists.Discovery Is Progressive — AGENTS.md Isn’t
This is the practical difference that matters most day to day. AGENTS.md content is in the prompt on turn one, whether the task needs it or not. Skills are discovered in three stages instead:
- Metadata only, at startup. Every skill’s
nameanddescriptionpopulate an<available_skills>list — small, cheap, always present. - Full content, on activation. Once a
triggers:keyword matches the conversation, or the agent decides a listed skill is relevant,invoke_skill()pulls the fullSKILL.mdbody into context. - Bundled resources, on demand. Anything in
scripts/,references/, orassets/loads only when the skill’s instructions actually point to it.
Path-triggered skills (paths: instead of triggers:) work differently again — they’re not listed in <available_skills> at all. Instead, the rule content gets appended to tool results in an <EXTRA_INFO> block the moment the agent edits a file matching the glob, e.g.:
---
name: api-input-validation
paths:
- "src/api/**/*.ts"
---Zero baseline cost until the agent actually touches src/api/, then the rule shows up attached to that specific edit. There’s no AGENTS.md equivalent of this — AGENTS.md has no scoping mechanism, so a rule that only applies to one directory either lives in AGENTS.md and gets read every turn regardless of relevance, or doesn’t get enforced automatically at all.
Where Each File Actually Belongs
| AGENTS.md / repo.md | SKILL.md (.agents/skills/) | Microagents (.openhands/microagents/, V0) | |
|---|---|---|---|
| Loaded | Every turn, from session start | On keyword/path match, or agent’s own judgment | Legacy — same idea as skills, older format |
| Best for | Build commands, architecture, standing rules that apply to nearly everything | Task-specific procedures: a review checklist, a migration script, a deploy runbook | Not recommended for new work |
| Token cost | Fixed, paid every turn regardless of relevance | Near-zero until activated | Same profile as skills, superseded by the standard |
| Portable across tools? | Yes — AGENTS.md is read by most other agents too | Yes — Agent Skills is now a cross-vendor open standard, not OpenHands-specific | No — OpenHands-specific format |
The practical rule of thumb OpenHands’s docs point toward: keep AGENTS.md short and universal — the stuff every task needs. Move anything long, conditional, or only-sometimes-relevant into a skill. If you’re migrating an existing microagents setup, the target is .agents/skills/, not a rewrite of AGENTS.md.
A Minimal Setup for a New OpenHands Repo
# AGENTS.md
## Setup
pnpm install && pnpm dev
## Conventions
- TypeScript strict mode, no untyped `any`.
- All API routes need a corresponding test under tests/api/..agents/skills/
└── db-migration/
└── SKILL.md---
name: db-migration
description: >
Generates and applies Prisma migrations safely, including a rollback
check. Use when the user asks to change the database schema.
triggers:
- migration
- schema change
- prisma
---
Run `pnpm prisma migrate dev --name <description>`, then confirm the
generated SQL doesn't drop a column with existing data before applying
it to a shared environment.Neither AGENTS.md nor a SKILL.md script directory is the place to put a database URL or an API key, and this is where OpenHands’s scripts/ convention gets worth being careful about — a bundled deploy or migration script is exactly the kind of file that ends up with a hardcoded credential if you’re not deliberate about it. 1Password’s CLI (op run) injects secrets into a script’s environment at execution time instead, so a skill’s scripts/deploy.sh can reference $DATABASE_URL without ever storing it in the repo the agent (or a teammate) is reading alongside your instruction files.
FAQ
Q1. Does OpenHands support AGENTS.md?
Yes. It’s auto-discovered at the repository root and its full content is injected into <REPO_CONTEXT> on every turn. OpenHands’s own SDK docs categorize it, alongside repo.md, under “Legacy Context” — still functional, but positioned as the older of two systems.
Q2. What’s the difference between AGENTS.md and OpenHands’s skills system?
AGENTS.md loads in full on every turn regardless of relevance. Skills (SKILL.md files under .agents/skills/) load progressively — metadata first, full content only when a triggers: keyword matches or the agent decides it’s relevant, and bundled scripts/references only when actually used.
Q3. Are OpenHands microagents the same as skills?
They’re the predecessor. .openhands/microagents/ is documented as the V0 (legacy) location; new repository-specific work is meant to go in .agents/skills/, following the cross-vendor Agent Skills open standard rather than an OpenHands-only format.
Q4. What’s the difference between triggers and paths in SKILL.md frontmatter?
triggers is a list of keywords — if one appears in the conversation, the skill’s full content is injected. paths is a list of glob patterns — the skill fires when the agent edits a matching file, appended to that tool result rather than listed as an available skill. The two are mutually exclusive on a single SKILL.md.
Q5. Is OpenHands’s SKILL.md format compatible with Claude Code or other tools?
Yes, at the base-spec level — OpenHands follows the Agent Skills standard Anthropic published as open in December 2025, which is also read by Claude Code, Cursor, GitHub, VS Code, and others. OpenHands’s triggers and paths fields are documented as OpenHands-specific extensions on top of that base spec, so a skill using only the required name/description fields is portable; one relying on triggers may not activate automatically the same way elsewhere.
Q6. Can I put secrets or API keys in AGENTS.md or a skill’s scripts folder? No — AGENTS.md and SKILL.md are both plain Markdown read as context or, for scripts, executed in the agent’s sandbox; neither is a credential store. Anything a bundled script needs (a database URL, an API token) should come from the environment at execution time rather than being written into the repo.
Related Reading on The Prompt Shelf
- Google Jules and AGENTS.md: The Complete 2026 Setup Guide
- Goose and AGENTS.md: Hierarchical Context Loading (2026)
- Amp’s AGENTS.md Discovery: The System-Wide Paths (2026)
- How Factory Droid CLI Discovers AGENTS.md (2026)
- AGENTS.md Not Loading? How to Debug It in 2026
Browse real AGENTS.md and SKILL.md examples from open-source repositories in our gallery.