Type to search the docs and updates.

Browse documentation

OpenHands native reference

Start with the OpenHands setup.

Native mappings

Skills

  • Written identically to the other .agents/skills/ tools, so the shared folder is written once.
  • The OpenHands skills docs document no field that keeps a skill user-only.
  • The SDK reads disable-model-invocation, but such a skill then runs only when a triggers keyword appears in a message, not by name.
  • Sync does not write it: disable-model-invocation is dropped with a note, and commands are skipped.

Agents

OpenHands loads .agents/agents/<name>.md in local conversations. The files share Goose's format: name, description, an optional free-form model, and the prompt body.

  • Each server in an agent's mcpServers is written in full under mcp_servers, the only form OpenHands takes. x-openhands.mcp_servers replaces the list.
  • Goose has no such key. While Goose writes the same folder, sync writes no servers and prints a note. Set outputs.openhands.agents-dir to .openhands/agents.
  • A generic tools list is dropped with a sync note, because OpenHands uses its own tool names (file_editor, terminal). Set x-openhands.tools with those names.
  • For an OpenHands profile that differs from Goose's, point outputs.openhands.agents-dir at .openhands/agents.
  • A portable color is dropped with a sync note, because Goose's agent frontmatter has no color. Set x-openhands.color to a Rich color name to write it.

Rules

An always-on rule goes into the ## Rules block of AGENTS.md, and so does a rule with a catch-all globs or paths. A rule is always-on when it has no globs, no paths, and no scope from its folder or frontmatter. A rule with file patterns but no directory scope also appears there with an Applies to line.

Path-triggered rules

A scoped rule becomes .agents/skills/<name>.md with a paths: list. OpenHands loads it when a touched file matches a pattern. The flat file keeps the rule out of Codex skill discovery. The outputs.openhands.skills-dir setting applies to both skills and rules. OpenHands path-triggered rules

A rule named skill, readme, or another name OpenHands reserves gets a -path-rule filename suffix. Sync adds a number when another rule already uses that filename. OpenHands sees each rule under a path-rule/ name, so it can load a rule and a skill with the same spec name.

A full agnostic-ai sync removes old rule folders recorded as generated. For a hand-written rule in the old <name>/SKILL.md form, import it and check the flat output before removing the original.

Hooks

OpenHands reads .openhands/hooks.json (outputs.openhands.hooks-file) per repository in Agent Canvas, OpenHands Cloud, and OpenHands Enterprise.

  • agnostic-ai hook run tests hooks before a session, with OpenHands's event data, shell, and timeout.
  • Hooks load only from the working folder, so a root .openhands/hooks.json does not apply when OpenHands works in a subfolder.
  • Six events: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart, SessionEnd.
  • Sync writes the Claude form (PascalCase keys inside a {"hooks": {...}} wrapper). OpenHands also accepts its own unwrapped snake_case form.
  • Each entry has command, type (always command), and optional timeout (seconds, default 60) and async.
  • matcher applies only to the two ToolUse events.
  • A Claude matcher such as Bash matches nothing, because OpenHands calls that tool terminal. Sync adds a note and does not rename it. OpenHands documents only terminal, *, and regex.

MCP

No file. OpenHands keeps MCP servers in its settings store. Add them in Agent Canvas under Customize > MCP Servers, or pass mcp_config to the SDK. It reads no project file and ignores the [mcp] section of a project config.toml (legacy V0).

  • A project or home MCP spec gets one sync note that points at Customize > MCP Servers.
  • An agent's mcpServers still reach its mcp_servers (Agents). A remote api_key becomes an Authorization: Bearer <key> header, as OpenHands sends it. An Authorization entry in headers wins.
  • timeout gets a sync note: it is not mapped into an agent's mcp_servers. Agent Canvas offers an optional SHTTP timeout in seconds in its server editor.

Environments

install writes .openhands/setup.sh, the repository setup script OpenHands runs each time it opens the repo.

  • The file has a #!/bin/bash line, the generated-file header, then install as written.
  • OpenHands runs chmod +x itself, so sync does not set the executable bit.
  • terminals (Cursor's long-running dev processes) gets a sync note, because the script runs once when the repo starts.
  • With several environment specs, the last install wins, as for Cursor.
Legacy config.toml and mcp.json
  • The next sync removes a config.toml that an earlier release wrote.
  • import openhands still reads the [mcp] table of a legacy config.toml into specs.
  • Only the unmaintained OpenHands-CLI reads ~/.openhands/mcp.json. sync --global no longer writes it.
  • The next sync --global removes the servers sync recorded as its own there, including a hand-written server an earlier sync adopted because it matched a spec exactly. Other servers stay.
  • Sync also removes the file when it created it and nothing else is left. Run sync --global --backup to keep a copy first.
  • import --global openhands still reads the file into specs.

Config keys

KeyDefault
outputs.openhands.agents-dir.agents/agents
outputs.openhands.skills-dir.agents/skills
outputs.openhands.hooks-file.openhands/hooks.json
outputs.openhands.setup-file.openhands/setup.sh

outputs.openhands.mcp-file no longer has an effect.

Import

agnostic-ai import openhands reads the OpenHands files back into specs:

SourceBecomes
AGENTS.md embedded ## Rules block (### <name> children)<rules>/<name>.md per rule
.agents/skills/<name>.md or .agents/skills/<name>/SKILL.md with paths<rules>/<name>.md with paths
.agents/skills/<name>/SKILL.md (+ bundled files)<skills>/<name>/SKILL.md, with triggers under x-openhands
.openhands/skills/ and .openhands/microagents/ (legacy)the same, read after .agents/skills/
flat <name>.md in any of those three directoriesa rule, or a skill when it has triggers (kept under x-openhands)
.agents/agents/<name>.md<agents>/<name>.md, with native skills, tools, permission_mode, color, hooks, max_iteration_per_run, max_budget_per_run, condenser, profile_store_dir, mcp_config and mcp_servers under x-openhands
.openhands/hooks.jsonone spec for consecutive commands with the same timeout and async in a matcher group
config.toml [mcp] table (legacy V0)<mcps>/<name>.yaml per server
.openhands/setup.sh<environments>/openhands-setup.yaml with the script as install
AGENTS.md.agnostic-ai/AGNOSTIC_AI.md
  • .agents/skills/ wins a name clash with the legacy folders, as in OpenHands.
  • Hooks import from both layouts. Snake_case pre_tool_use comes back as PreToolUse.
  • Fresh hook imports keep native command order with position prefixes in their spec names. Keep those prefixes when renaming imported hooks.
  • Import stops on an agent whose mcp_servers or mcp_config holds a literal credential, such as API_KEY: sk-..., because specs are committed. Replace it with a ${VAR} or $VAR reference, which OpenHands resolves at load time. References are kept as written.

Import loses these details (none change what OpenHands loads):

  • Unnamed sse_servers and shttp_servers entries are named after the URL host (docs-example-test).
  • A rule scoped by its folder comes back as the paths glob it was widened to.
  • An environment spec keeps only install. Its name and terminals are lost.