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 atriggerskeyword appears in a message, not by name. - Sync does not write it:
disable-model-invocationis 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
mcpServersis written in full undermcp_servers, the only form OpenHands takes.x-openhands.mcp_serversreplaces 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-dirto.openhands/agents. - A generic
toolslist is dropped with a sync note, because OpenHands uses its own tool names (file_editor,terminal). Setx-openhands.toolswith those names. - For an OpenHands profile that differs from Goose's, point
outputs.openhands.agents-dirat.openhands/agents. - A portable
coloris dropped with a sync note, because Goose's agent frontmatter has no color. Setx-openhands.colorto 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
agnostic-ai hook runtests hooks before a session, with OpenHands's event data, shell, and timeout.- Hooks load only from the working folder, so a root
.openhands/hooks.jsondoes 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(alwayscommand), and optionaltimeout(seconds, default 60) andasync. matcherapplies only to the two ToolUse events.- A Claude matcher such as
Bashmatches nothing, because OpenHands calls that toolterminal. Sync adds a note and does not rename it. OpenHands documents onlyterminal,*, 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
mcpServersstill reach itsmcp_servers(Agents). A remoteapi_keybecomes anAuthorization: Bearer <key>header, as OpenHands sends it. AnAuthorizationentry inheaderswins. timeoutgets a sync note: it is not mapped into an agent'smcp_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/bashline, the generated-file header, theninstallas written. - OpenHands runs
chmod +xitself, 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
installwins, as for Cursor.
Legacy config.toml and mcp.json
- The next sync removes a
config.tomlthat an earlier release wrote. import openhandsstill reads the[mcp]table of a legacyconfig.tomlinto specs.- Only the unmaintained OpenHands-CLI reads
~/.openhands/mcp.json.sync --globalno longer writes it. - The next
sync --globalremoves 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 --backupto keep a copy first. import --global openhandsstill reads the file into specs.
Config keys
| Key | Default |
|---|---|
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:
| Source | Becomes |
|---|---|
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 directories | a 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.json | one 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_usecomes back asPreToolUse. - 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_serversormcp_configholds a literal credential, such asAPI_KEY: sk-..., because specs are committed. Replace it with a${VAR}or$VARreference, which OpenHands resolves at load time. References are kept as written.
Import loses these details (none change what OpenHands loads):
- Unnamed
sse_serversandshttp_serversentries are named after the URL host (docs-example-test). - A rule scoped by its folder comes back as the
pathsglob it was widened to. - An environment spec keeps only
install. Its name andterminalsare lost.