Customize OpenHands with skills, AGENTS.md, setup.sh and MCP

AGENTS.md at the repository root is included in the initial system prompt. Keep it short: the purpose of the repo, how to set it up, its structure, and the CI checks it must pass. OpenHands also recognizes CLAUDE.md and GEMINI.md as model specific repository context.

• Repository skills: .agents/skills/SKILL_NAME/SKILL.md (recommended for new skills).
• Legacy paths .openhands/skills and .openhands/microagents are still supported.
• User skills: ~/.agents/skills, available in all of that user's conversations.
• The skill name in the frontmatter must match its parent directory name.

---
name: release-checklist
description: Prepare and verify a release checklist. Use when creating release notes or publishing a release.
---

Check the version, changelog, validation commands, and release notes before publishing.

Add a triggers list to the frontmatter and the skill loads only when one of those words appears in a message. This keeps specialized guidance, such as GitHub or GitLab instructions, out of the context until it is needed.

---
name: github
description: How to work with the GitHub API in this environment.
triggers:
- github
- git
---

You have access to an environment variable, GITHUB_TOKEN, which allows you to interact with the GitHub API.

Put a setup.sh script in the .openhands directory at the repository root. It runs whenever OpenHands starts working with the repository, so use it to set environment variables and install dependencies.

#!/bin/bash
export MY_ENV_VAR="my value"
sudo apt-get update
sudo apt-get install -y lsof
cd frontend && npm install ; cd ..

A .openhands/hooks.json file can run scripts at key points, for example to block dangerous commands or log tool use. Stop hooks can block task completion until formatting, linting or tests pass, and the docs say checks in the older pre-commit.sh should move to Stop hooks.

Current OpenHands releases do not read MCP servers from config.toml; that format was for the legacy V0 version. Add servers in the UI under Customize, then MCP Servers, or with the CLI, which writes them to ~/.openhands/mcp.json.

uv tool install openhands --python 3.12
openhands
openhands mcp add YOUR_NAME --transport http YOUR_SERVER_URL
openhands mcp add YOUR_NAME --transport stdio --env "KEY=YOUR_VALUE" YOUR_COMMAND -- YOUR_ARGS
openhands mcp list
openhands mcp remove YOUR_NAME

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

The CLI needs Python 3.12 or newer. On first launch it walks you through LLM settings, which it stores in ~/.openhands/settings.json.