From 8a1905bcb5d07c2eb75bf981643690b7c1e35419 Mon Sep 17 00:00:00 2001 From: enyst Date: Sat, 21 Feb 2026 04:24:50 +0000 Subject: [PATCH 01/19] skills: add modify-openhands skill Co-authored-by: openhands --- .plugin/marketplace.json | 15 ++ skills/modify-openhands/README.md | 8 + skills/modify-openhands/SKILL.md | 199 ++++++++++++++++++ .../references/ARCHITECTURE.md | 103 +++++++++ .../references/INSTALLATION_MODES.md | 114 ++++++++++ .../modify-openhands/references/TEMPLATES.md | 154 ++++++++++++++ 6 files changed, 593 insertions(+) create mode 100644 skills/modify-openhands/README.md create mode 100644 skills/modify-openhands/SKILL.md create mode 100644 skills/modify-openhands/references/ARCHITECTURE.md create mode 100644 skills/modify-openhands/references/INSTALLATION_MODES.md create mode 100644 skills/modify-openhands/references/TEMPLATES.md diff --git a/.plugin/marketplace.json b/.plugin/marketplace.json index 14acf5a..0d1008e 100644 --- a/.plugin/marketplace.json +++ b/.plugin/marketplace.json @@ -226,6 +226,21 @@ "cloud-native" ] }, + { + "name": "modify-openhands", + "source": "./modify-openhands", + "description": "Decide how to modify OpenHands behavior persistently: skills, AGENTS.md, hooks, plugins, MCP servers, or code changes in OpenHands-CLI and software-agent-sdk.", + "category": "development", + "keywords": [ + "openhands", + "customization", + "skills", + "hooks", + "plugins", + "mcp", + "uv" + ] + }, { "name": "notion", "source": "./notion", diff --git a/skills/modify-openhands/README.md b/skills/modify-openhands/README.md new file mode 100644 index 0000000..50d67a2 --- /dev/null +++ b/skills/modify-openhands/README.md @@ -0,0 +1,8 @@ +# modify-openhands + +This skill is a playbook for “self-modification” requests: + +- deciding whether the user actually needs code changes, vs. +- adding a repo/user skill, always-on repo instructions (`AGENTS.md`), hooks (`.openhands/hooks.json`), plugins, or MCP tooling. + +The canonical instructions live in [`SKILL.md`](SKILL.md). diff --git a/skills/modify-openhands/SKILL.md b/skills/modify-openhands/SKILL.md new file mode 100644 index 0000000..9f45bc3 --- /dev/null +++ b/skills/modify-openhands/SKILL.md @@ -0,0 +1,199 @@ +--- +name: modify-openhands +description: Decide how to make OpenHands “modify itself” (persistent behavior changes) by choosing between repo/user skills, always-on instructions, hooks, plugins, MCP servers, or code changes in OpenHands-CLI and software-agent-sdk. Includes uv + uv tool workflows and restart/reload behavior. +triggers: +- modify yourself +- change your behavior +- customize openhands +- self-modify +- self modification +- hack openhands +- .agents/skills +- hooks.json +- plugin.json +- uv tool install +--- + +# Modify OpenHands (self-modification playbook) + +When a user says things like “modify yourself to do X” or “remember this next time”, **don’t jump to editing Python code**. +OpenHands has multiple extensibility layers; choose the *smallest*, *safest*, and *most persistent* mechanism that matches the user’s intent. + +This skill is about **persistent** changes that should still apply after the user restarts the CLI / app. + +## 0) First: clarify what kind of change the user wants + +Ask these questions (one at a time): + +1. **Persistence scope**: Should this change apply… + - only in *this* conversation? + - for this *repository/workspace*? + - for *all repos on this machine* (user-global)? + - for *everyone* (contribution upstream / extensions registry)? +2. **Change type**: Is it primarily… + - instructions/workflow (“when I ask for X, do Y”)? + - a safety/policy constraint (“never run rm -rf”, “ask before network calls”)? + - a new capability/tool integration (GitHub, Jira, internal APIs, etc.)? + - a bug fix / UI change in the CLI or SDK? +3. **Where do they run OpenHands?** + - `uv tool install openhands` (tool environment) + - from a local clone (developer workflow) + - via a remote runtime / server + +Then follow the decision tree below. + +## 1) Prefer non-code extensibility (often enough) + +### 1.1 Write a skill (AgentSkills / progressive disclosure) + +Use when the user wants repeatable expertise/workflows, e.g.: +- “When I say ‘release notes’, use this structure” +- “Here’s how we do migrations in our company” +- “We always run `make lint` before committing” + +**Where to put it (in priority order):** + +1. **Project-local (recommended):** `/.agents/skills//SKILL.md` +2. Legacy OpenHands path: `/.openhands/skills//SKILL.md` +3. **User-global:** `~/.agents/skills//SKILL.md` + +Notes: +- **Project skills override user + public skills** (same `name`). This is the simplest way to “patch” a public skill locally. +- Add `triggers:` only when you really want automatic activation; prefer **distinctive phrases** to avoid injecting the skill on unrelated messages. + +See: [Templates](references/TEMPLATES.md#agentskillsskillmd-template). + +### 1.2 Add always-on repo instructions (AGENTS.md) + +Use when the user wants **always-applied** guidance for a repository (style, commands, guardrails, conventions): + +- Create or edit `/AGENTS.md` (or model-specific variants like `CLAUDE.md`, `GEMINI.md` if your environment supports them). +- Put the repo rules there. + +This gets loaded at conversation start as “always-on context” (not progressive disclosure). + +### 1.3 Add hooks (policy/automation) via `.openhands/hooks.json` + +Use when the user wants **enforcement** or **automation** around tool usage, e.g.: +- “Before any git commit, run tests.” +- “Block any command that tries to access prod without approval.” +- “Reject tool calls that write outside the repo.” + +Hooks are executed on lifecycle events (like `pre_tool_use`) and can **allow / block / modify** actions. + +See: [Hook templates](references/TEMPLATES.md#hookshooksjson-template) and [Hook architecture notes](references/ARCHITECTURE.md#hooks). + +### 1.4 Add tools via MCP (`.mcp.json`) + +Use when the user wants a **new tool** (capability) that should be available to the agent: +- internal HTTP APIs +- local services +- language servers +- DB query endpoints + +MCP servers are configured via `.mcp.json` (often at repo root, depending on the host product). + +See: [MCP template](references/TEMPLATES.md#mcp-template). + +### 1.5 Package it as a plugin (shareable bundle) + +Use when the change should be **portable** across repos or shared with others, and it includes more than just instructions: +- skills + hooks + MCP config together +- optional slash commands and/or specialized agents + +Plugins follow the Claude Code-compatible structure, with `.plugin/plugin.json` (or `.claude-plugin/plugin.json`). + +See: [Plugin template](references/TEMPLATES.md#plugin-template) and [Plugin architecture notes](references/ARCHITECTURE.md#plugins). + +## 2) When code changes are actually required + +Choose the correct codebase / package: + +- **CLI UX, TUI widgets, slash commands, config files** → `OpenHands/OpenHands-CLI` +- **Agent runtime logic, skill loading, hooks system, plugin loader, event model** → `OpenHands/software-agent-sdk` → `openhands-sdk` +- **Built-in tools (Terminal, File Editor, Task Tracker, etc.)** → `OpenHands/software-agent-sdk` → `openhands-tools` +- **Workspace mounting / file sync / workspace abstraction** → `OpenHands/software-agent-sdk` → `openhands-workspace` + +If you’re not sure, start by reproducing the issue and locating the code path. + +## 3) uv development workflows (including `uv tool install openhands`) + +### 3.1 Recommended: run from a local clone (developer workflow) + +**CLI** + +```bash +git clone https://github.com/OpenHands/OpenHands-CLI.git +cd OpenHands-CLI +uv sync --group dev +uv run openhands +``` + +**SDK** + +```bash +git clone https://github.com/OpenHands/software-agent-sdk.git +cd software-agent-sdk +uv sync --group dev +uv run pytest +``` + +### 3.2 If the user installed OpenHands via `uv tool install openhands` + +You have two good options: + +#### Option A: test-run a local checkout without replacing the installed tool + +```bash +uv tool run --from /path/to/OpenHands-CLI openhands +``` + +This is the safest way to validate a change. + +#### Option B: replace the installed tool with an editable checkout + +```bash +uv tool install --force --editable /path/to/OpenHands-CLI +``` + +Now, the next time they run `openhands`, it will use the editable code. + +See: [uv tool notes](references/INSTALLATION_MODES.md#uv-tool-mode). + +### 3.3 Developing the SDK *while* running the CLI + +Important constraint: **the CLI pins exact SDK/tool versions** (e.g., `openhands-sdk==1.11.4`). + +To use a local SDK checkout: + +1. **Match versions**: check what the CLI requires in `OpenHands-CLI/pyproject.toml`. +2. **Check out the matching tag/commit** of `software-agent-sdk` (or temporarily loosen pins for development). +3. Install the SDK packages in editable mode in the same environment that runs the CLI. + +Common approaches: +- **Run CLI from source** and set `tool.uv.sources` to local paths. +- In `uv tool` mode, use an `--overrides` file to force a local path dependency. + +See: [SDK + CLI versioning](references/INSTALLATION_MODES.md#sdk-vs-cli-version-pins). + +## 4) What requires a restart to take effect? + +- **Skills / AGENTS.md**: typically loaded at conversation start → restart the app/CLI (or start a new conversation) to guarantee reload. +- **Hooks (.openhands/hooks.json)**: loaded when the agent/conversation initializes → restart to guarantee reload. +- **Plugins**: loaded when the conversation initializes → restart to guarantee reload. +- **Editable Python code (uv tool `--editable` or local `uv run`)**: changes apply the next time the Python process starts. + +## 5) Verification checklist + +After making a “self-modification” change: + +1. Restart OpenHands. +2. In the CLI, run `/skills` to confirm the expected skills/hooks/MCPs are loaded. +3. Trigger the workflow with a tiny, deterministic test prompt. +4. If it’s a code change, run the smallest relevant test suite (or add one). + +## References + +- [Architecture: CLI vs SDK vs skills/hooks/plugins](references/ARCHITECTURE.md) +- [Installation modes: `uv tool` vs `uv run` and version pinning](references/INSTALLATION_MODES.md) +- [Templates: SKILL.md, hooks.json, plugin.json, .mcp.json](references/TEMPLATES.md) diff --git a/skills/modify-openhands/references/ARCHITECTURE.md b/skills/modify-openhands/references/ARCHITECTURE.md new file mode 100644 index 0000000..aeef212 --- /dev/null +++ b/skills/modify-openhands/references/ARCHITECTURE.md @@ -0,0 +1,103 @@ +# OpenHands extensibility architecture (CLI + SDK) + +OpenHands “behavior” can be modified at multiple layers. The key is to choose the layer that matches the user’s intent. + +## Components + +### OpenHands CLI (`OpenHands/OpenHands-CLI`) + +- Python package name: `openhands` +- Entry points: `openhands`, `openhands-acp` +- Responsibilities: + - Terminal UI (Textual) + - Loading config + wiring up an SDK `Agent` + - Choosing tools and building an `AgentContext` + +In the CLI codebase, look for where it creates the `AgentContext` and enables: +- project skills +- user skills +- public skills + +### Software Agent SDK monorepo (`OpenHands/software-agent-sdk`) + +This repo is a **uv workspace** that produces multiple packages: + +- `openhands-sdk` (module: `openhands.sdk`) + - agent runtime primitives (Agent, Conversation, Event model) + - context loading (skills) + - hooks system + - plugin loader + +- `openhands-tools` (module: `openhands.tools`) + - built-in tools used by many OpenHands products + +- `openhands-workspace` (module: `openhands.workspace`) + - workspace mounting, file sync abstractions + +- `openhands-agent-server` + - server-side runtime + +## Skills + +Skills are loaded from multiple locations; **project-local skills override user + public**. + +Common locations: + +- Project-local: + - `/.agents/skills/` + - `/.openhands/skills/` (legacy) + +- User-global: + - `~/.agents/skills/` + - `~/.openhands/skills/` (legacy) + +- Public registry: + - `https://github.com/OpenHands/extensions` (cached locally under `~/.openhands/skills-cache/`) + +Skill types: + +- **AgentSkills format**: a directory with `SKILL.md` (progressive disclosure) +- **Always-on instructions**: repo instruction files like `AGENTS.md` (loaded at conversation start) + +## Hooks + +Hooks are configured via JSON and executed on events (e.g. `pre_tool_use`). + +Typical locations (depending on product / SDK config): + +- `/.openhands/hooks.json` +- `~/.openhands/hooks.json` + +Hook scripts receive an event payload on stdin as JSON and respond with a decision. + +## Plugins + +Plugins are bundles of: + +- skills +- hooks +- MCP config +- optional commands and agents + +They follow the Claude Code-compatible directory structure: + +``` +my-plugin/ +├── .plugin/ +│ └── plugin.json +├── skills/ +├── hooks/ +│ └── hooks.json +├── .mcp.json +└── README.md +``` + +Plugins can be: +- loaded from a local path +- fetched from GitHub/git URLs and cached under `~/.openhands/cache/plugins/` + +## MCP servers (tools) + +MCP servers provide tool endpoints to the agent. + +They are configured via `.mcp.json` (location depends on host product). Plugins can also provide MCP config. diff --git a/skills/modify-openhands/references/INSTALLATION_MODES.md b/skills/modify-openhands/references/INSTALLATION_MODES.md new file mode 100644 index 0000000..18b965b --- /dev/null +++ b/skills/modify-openhands/references/INSTALLATION_MODES.md @@ -0,0 +1,114 @@ +# Installation and development modes (uv) + +This reference is for making “persistent self-modifications” that apply after restart. + +## `uv run` (project environment) mode + +Use when you are developing from a git clone. + +- `uv sync` installs dependencies into a project-local `.venv/` (and/or uses the uv lockfile). +- `uv run ...` runs inside that environment. + +Typical CLI dev flow: + +```bash +cd OpenHands-CLI +uv sync --group dev +uv run openhands +``` + +Typical SDK dev flow: + +```bash +cd software-agent-sdk +uv sync --group dev +uv run pytest +``` + +### Pros + +- Simple debugging (local sources) +- Easy to run tests + linters +- No global tool replacement needed + +### Cons + +- You must run `openhands` via `uv run openhands` (or ensure the venv is on PATH) + +## `uv tool install openhands` (tool environment) mode + +In this mode, `uv` installs the CLI into a dedicated tool environment and exposes a shim executable. + +### Inspect installed tools + +```bash +uv tool list +uv tool dir +``` + +If `openhands` is installed and not found on PATH, run: + +```bash +uv tool update-shell +``` + +### Replace the tool with an editable local checkout + +This is the most common way to run a modified CLI *after restart*: + +```bash +uv tool install --force --editable /path/to/OpenHands-CLI +``` + +After that, `openhands` should use the editable sources. + +### Run a local checkout without installing + +This is the safest way to test a change: + +```bash +uv tool run --from /path/to/OpenHands-CLI openhands +``` + +## SDK vs CLI version pins + +The CLI often pins exact versions of: + +- `openhands-sdk` +- `openhands-tools` +- `openhands-workspace` + +If you want to use a local SDK checkout *together with the CLI*, you must handle that pinning. + +### What usually works + +1. Check the versions the CLI requires: + - `OpenHands-CLI/pyproject.toml` +2. Check out the matching tag/commit in `software-agent-sdk`. +3. Install the matching SDK packages in editable mode into the environment that runs the CLI. + +### What commonly fails + +Trying to install an SDK checkout at version `X` into an environment where the CLI requires `openhands-sdk==Y`. + +### Using `--overrides` for development + +As a last resort for local development, you can override pinned deps. + +Create a file (e.g. `overrides.txt`) containing a direct URL or local path spec: + +```text +openhands-sdk @ file:///absolute/path/to/software-agent-sdk/openhands-sdk +openhands-tools @ file:///absolute/path/to/software-agent-sdk/openhands-tools +openhands-workspace @ file:///absolute/path/to/software-agent-sdk/openhands-workspace +``` + +Then install the CLI tool using that overrides file: + +```bash +uv tool install --force --editable /path/to/OpenHands-CLI --overrides overrides.txt +``` + +Notes: +- This is intentionally “break glass”; it can produce a mismatched runtime. +- Prefer aligning versions whenever possible. diff --git a/skills/modify-openhands/references/TEMPLATES.md b/skills/modify-openhands/references/TEMPLATES.md new file mode 100644 index 0000000..6aa0a6f --- /dev/null +++ b/skills/modify-openhands/references/TEMPLATES.md @@ -0,0 +1,154 @@ +# Templates + +Use these as starting points when implementing a “self-modification” without changing OpenHands code. + +## AgentSkills (`SKILL.md`) template + +Create a directory: + +``` +/.agents/skills// +└── SKILL.md +``` + +Example `SKILL.md`: + +```md +--- +name: my-team-workflow +description: Our team’s workflow for X. Use when the user asks about X. +triggers: +- team x workflow +- how do we do x +--- + +# Our workflow for X + +## When to use + +Use this workflow when... + +## Steps + +1. ... +2. ... + +## Verification + +- Run: `...` +``` + +Notes: +- Keep triggers distinctive. +- Keep the file focused; put deep details in `references/`. + +## Always-on repo instructions (`AGENTS.md`) template + +Create `/AGENTS.md`: + +```md +# Project rules + +## Build / run +- `make install` +- `make test` + +## Code style +- Ruff formatting + +## Safety +- Never run destructive commands without asking +``` + +## Hooks (`.openhands/hooks.json`) template + +Create `/.openhands/hooks.json`: + +```json +{ + "pre_tool_use": [ + { + "command": "bash .openhands/hooks/block-dangerous.sh", + "matchers": { + "tool_name": "terminal" + } + } + ] +} +``` + +Then create the script `/.openhands/hooks/block-dangerous.sh`: + +```bash +#!/usr/bin/env bash + +# stdin: HookEvent JSON +payload="$(cat)" + +# Very small example: block rm -rf +if echo "$payload" | grep -q "rm -rf"; then + # A hook can output a decision JSON; exact schema depends on the SDK. + # Prefer copying the schema from current SDK docs/tests. + echo '{"decision":"block","reason":"Blocked destructive command"}' + exit 0 +fi + +echo '{"decision":"allow"}' +``` + +Notes: +- This is intentionally simplified. +- For production hooks, use a real JSON parser (`jq`) and follow the SDK schema. + +## Plugin template + +Plugin structure: + +``` +my-plugin/ +├── .plugin/ +│ └── plugin.json +├── skills/ +│ └── my-skill/ +│ └── SKILL.md +├── hooks/ +│ └── hooks.json +├── .mcp.json +└── README.md +``` + +Minimal `.plugin/plugin.json` (fields vary by plugin schema): + +```json +{ + "name": "my-plugin", + "version": "0.1.0", + "description": "My custom OpenHands behavior", + "author": { + "name": "Example", + "email": "dev@example.com" + } +} +``` + +## MCP template (`.mcp.json`) + +Minimal example: + +```json +{ + "mcpServers": { + "my-server": { + "command": "python", + "args": ["-m", "my_mcp_server"], + "env": { + "MY_SERVER_TOKEN": "$MY_SERVER_TOKEN" + } + } + } +} +``` + +Notes: +- Never hardcode real secrets in files. +- Prefer environment variables. From 52633f715a48e09ae7308fc0fec46c6a519b131b Mon Sep 17 00:00:00 2001 From: openhands Date: Sat, 21 Feb 2026 05:41:42 +0000 Subject: [PATCH 02/19] skills: trim modify-openhands and clarify MCP paths Co-authored-by: openhands --- skills/modify-openhands/SKILL.md | 69 ++++--------------- .../modify-openhands/references/TEMPLATES.md | 18 ++--- 2 files changed, 22 insertions(+), 65 deletions(-) diff --git a/skills/modify-openhands/SKILL.md b/skills/modify-openhands/SKILL.md index 9f45bc3..d5e051e 100644 --- a/skills/modify-openhands/SKILL.md +++ b/skills/modify-openhands/SKILL.md @@ -23,7 +23,7 @@ This skill is about **persistent** changes that should still apply after the use ## 0) First: clarify what kind of change the user wants -Ask these questions (one at a time): +Clarify the **scope** and **type** of the change (skip questions the user already answered): 1. **Persistence scope**: Should this change apply… - only in *this* conversation? @@ -91,7 +91,10 @@ Use when the user wants a **new tool** (capability) that should be available to - language servers - DB query endpoints -MCP servers are configured via `.mcp.json` (often at repo root, depending on the host product). +MCP server configuration is **product-specific**: + +- **OpenHands-CLI** persists MCP servers in `~/.openhands/mcp.json` (or `$OPENHANDS_PERSISTENCE_DIR/mcp.json`). +- **Software Agent SDK skills/plugins** use a **per-skill/per-plugin** `.mcp.json` file located inside the skill/plugin directory. See: [MCP template](references/TEMPLATES.md#mcp-template). @@ -118,63 +121,15 @@ If you’re not sure, start by reproducing the issue and locating the code path. ## 3) uv development workflows (including `uv tool install openhands`) -### 3.1 Recommended: run from a local clone (developer workflow) - -**CLI** - -```bash -git clone https://github.com/OpenHands/OpenHands-CLI.git -cd OpenHands-CLI -uv sync --group dev -uv run openhands -``` - -**SDK** - -```bash -git clone https://github.com/OpenHands/software-agent-sdk.git -cd software-agent-sdk -uv sync --group dev -uv run pytest -``` - -### 3.2 If the user installed OpenHands via `uv tool install openhands` - -You have two good options: - -#### Option A: test-run a local checkout without replacing the installed tool - -```bash -uv tool run --from /path/to/OpenHands-CLI openhands -``` - -This is the safest way to validate a change. - -#### Option B: replace the installed tool with an editable checkout - -```bash -uv tool install --force --editable /path/to/OpenHands-CLI -``` - -Now, the next time they run `openhands`, it will use the editable code. - -See: [uv tool notes](references/INSTALLATION_MODES.md#uv-tool-mode). - -### 3.3 Developing the SDK *while* running the CLI - -Important constraint: **the CLI pins exact SDK/tool versions** (e.g., `openhands-sdk==1.11.4`). - -To use a local SDK checkout: - -1. **Match versions**: check what the CLI requires in `OpenHands-CLI/pyproject.toml`. -2. **Check out the matching tag/commit** of `software-agent-sdk` (or temporarily loosen pins for development). -3. Install the SDK packages in editable mode in the same environment that runs the CLI. +Keep this section **high-level**; the goal is to pick the right workflow, not memorize `uv`. -Common approaches: -- **Run CLI from source** and set `tool.uv.sources` to local paths. -- In `uv tool` mode, use an `--overrides` file to force a local path dependency. +- If they run OpenHands from a **local clone**: use `uv sync` + `uv run openhands`. +- If they installed OpenHands via **`uv tool install openhands`**: + - safest: `uv tool run --from /path/to/OpenHands-CLI openhands` + - persistent: `uv tool install --force --editable /path/to/OpenHands-CLI` +- If they need to modify the **SDK** while running the CLI, remember: the CLI often **pins exact SDK/tool versions**. Prefer aligning versions; use overrides only for local development. -See: [SDK + CLI versioning](references/INSTALLATION_MODES.md#sdk-vs-cli-version-pins). +Details: [Installation modes (`uv tool` vs `uv run`)](references/INSTALLATION_MODES.md). ## 4) What requires a restart to take effect? diff --git a/skills/modify-openhands/references/TEMPLATES.md b/skills/modify-openhands/references/TEMPLATES.md index 6aa0a6f..21bc4c9 100644 --- a/skills/modify-openhands/references/TEMPLATES.md +++ b/skills/modify-openhands/references/TEMPLATES.md @@ -85,20 +85,22 @@ Then create the script `/.openhands/hooks/block-dangerous.sh`: # stdin: HookEvent JSON payload="$(cat)" -# Very small example: block rm -rf -if echo "$payload" | grep -q "rm -rf"; then - # A hook can output a decision JSON; exact schema depends on the SDK. - # Prefer copying the schema from current SDK docs/tests. - echo '{"decision":"block","reason":"Blocked destructive command"}' +# Example: block `rm -rf ...` for Terminal tool calls. +# Requires: jq +cmd="$(echo "$payload" | jq -r '.tool_input.command // ""')" + +if echo "$cmd" | grep -Eq '(^|[[:space:]])rm[[:space:]]+-rf([[:space:]]|$)'; then + # HookExecutor parses JSON on stdout; "decision" must be "allow" or "deny". + jq -n --arg reason "Blocked destructive command" '{"decision":"deny","reason":$reason}' exit 0 fi -echo '{"decision":"allow"}' +jq -n '{"decision":"allow"}' ``` Notes: -- This is intentionally simplified. -- For production hooks, use a real JSON parser (`jq`) and follow the SDK schema. +- Prefer parsing the structured fields (like `.tool_input.command`) rather than grepping raw JSON. +- The exact `tool_input` shape is tool-specific; inspect the SDK `HookEvent` schema and your tool inputs. ## Plugin template From 3631d98db9f3ff5657b5264fd164ad87094e2e7c Mon Sep 17 00:00:00 2001 From: openhands Date: Sat, 21 Feb 2026 06:02:10 +0000 Subject: [PATCH 03/19] skills: rename modify-openhands to adapt-yourself Co-authored-by: openhands --- .plugin/marketplace.json | 6 +++--- skills/{modify-openhands => adapt-yourself}/README.md | 2 +- skills/{modify-openhands => adapt-yourself}/SKILL.md | 4 ++-- .../references/ARCHITECTURE.md | 0 .../references/INSTALLATION_MODES.md | 0 .../references/TEMPLATES.md | 0 6 files changed, 6 insertions(+), 6 deletions(-) rename skills/{modify-openhands => adapt-yourself}/README.md (94%) rename skills/{modify-openhands => adapt-yourself}/SKILL.md (97%) rename skills/{modify-openhands => adapt-yourself}/references/ARCHITECTURE.md (100%) rename skills/{modify-openhands => adapt-yourself}/references/INSTALLATION_MODES.md (100%) rename skills/{modify-openhands => adapt-yourself}/references/TEMPLATES.md (100%) diff --git a/.plugin/marketplace.json b/.plugin/marketplace.json index 0d1008e..48736b3 100644 --- a/.plugin/marketplace.json +++ b/.plugin/marketplace.json @@ -227,9 +227,9 @@ ] }, { - "name": "modify-openhands", - "source": "./modify-openhands", - "description": "Decide how to modify OpenHands behavior persistently: skills, AGENTS.md, hooks, plugins, MCP servers, or code changes in OpenHands-CLI and software-agent-sdk.", + "name": "adapt-yourself", + "source": "./adapt-yourself", + "description": "Decide how to make OpenHands adapt/improve itself persistently: skills, AGENTS.md, hooks, plugins, MCP servers, or code changes in OpenHands-CLI and software-agent-sdk.", "category": "development", "keywords": [ "openhands", diff --git a/skills/modify-openhands/README.md b/skills/adapt-yourself/README.md similarity index 94% rename from skills/modify-openhands/README.md rename to skills/adapt-yourself/README.md index 50d67a2..3996930 100644 --- a/skills/modify-openhands/README.md +++ b/skills/adapt-yourself/README.md @@ -1,4 +1,4 @@ -# modify-openhands +# adapt-yourself This skill is a playbook for “self-modification” requests: diff --git a/skills/modify-openhands/SKILL.md b/skills/adapt-yourself/SKILL.md similarity index 97% rename from skills/modify-openhands/SKILL.md rename to skills/adapt-yourself/SKILL.md index d5e051e..3f58c5f 100644 --- a/skills/modify-openhands/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -1,6 +1,6 @@ --- -name: modify-openhands -description: Decide how to make OpenHands “modify itself” (persistent behavior changes) by choosing between repo/user skills, always-on instructions, hooks, plugins, MCP servers, or code changes in OpenHands-CLI and software-agent-sdk. Includes uv + uv tool workflows and restart/reload behavior. +name: adapt-yourself +description: Decide how to make OpenHands adapt/improve itself persistently (after restart) by choosing between repo/user skills, always-on instructions, hooks, plugins, MCP servers, or code changes in OpenHands-CLI and software-agent-sdk. Includes uv + uv tool workflows and restart/reload behavior. triggers: - modify yourself - change your behavior diff --git a/skills/modify-openhands/references/ARCHITECTURE.md b/skills/adapt-yourself/references/ARCHITECTURE.md similarity index 100% rename from skills/modify-openhands/references/ARCHITECTURE.md rename to skills/adapt-yourself/references/ARCHITECTURE.md diff --git a/skills/modify-openhands/references/INSTALLATION_MODES.md b/skills/adapt-yourself/references/INSTALLATION_MODES.md similarity index 100% rename from skills/modify-openhands/references/INSTALLATION_MODES.md rename to skills/adapt-yourself/references/INSTALLATION_MODES.md diff --git a/skills/modify-openhands/references/TEMPLATES.md b/skills/adapt-yourself/references/TEMPLATES.md similarity index 100% rename from skills/modify-openhands/references/TEMPLATES.md rename to skills/adapt-yourself/references/TEMPLATES.md From e3b6364d26c3b0d87c42e046f64bde37445d534a Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Sat, 21 Feb 2026 07:22:10 +0100 Subject: [PATCH 04/19] Apply suggestion from @enyst --- skills/adapt-yourself/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/adapt-yourself/SKILL.md b/skills/adapt-yourself/SKILL.md index 3f58c5f..2fd99f2 100644 --- a/skills/adapt-yourself/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -11,7 +11,6 @@ triggers: - .agents/skills - hooks.json - plugin.json -- uv tool install --- # Modify OpenHands (self-modification playbook) From edcb18f827f004c7d6d8653239e8874e5b593112 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Sat, 21 Feb 2026 07:24:48 +0100 Subject: [PATCH 05/19] Apply suggestion from @enyst --- skills/adapt-yourself/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/adapt-yourself/SKILL.md b/skills/adapt-yourself/SKILL.md index 2fd99f2..2d05621 100644 --- a/skills/adapt-yourself/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -48,7 +48,7 @@ Then follow the decision tree below. Use when the user wants repeatable expertise/workflows, e.g.: - “When I say ‘release notes’, use this structure” - “Here’s how we do migrations in our company” -- “We always run `make lint` before committing” +- “Read the Daytona docs and learn how to use it” **Where to put it (in priority order):** From 3c3536ca04be59a56de9573c326e734000299300 Mon Sep 17 00:00:00 2001 From: openhands Date: Sat, 21 Feb 2026 06:27:41 +0000 Subject: [PATCH 06/19] skills: remove legacy .openhands skill paths Co-authored-by: openhands --- skills/adapt-yourself/SKILL.md | 3 +-- skills/adapt-yourself/references/ARCHITECTURE.md | 2 -- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/skills/adapt-yourself/SKILL.md b/skills/adapt-yourself/SKILL.md index 2d05621..19587f7 100644 --- a/skills/adapt-yourself/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -53,8 +53,7 @@ Use when the user wants repeatable expertise/workflows, e.g.: **Where to put it (in priority order):** 1. **Project-local (recommended):** `/.agents/skills//SKILL.md` -2. Legacy OpenHands path: `/.openhands/skills//SKILL.md` -3. **User-global:** `~/.agents/skills//SKILL.md` +2. **User-global:** `~/.agents/skills//SKILL.md` Notes: - **Project skills override user + public skills** (same `name`). This is the simplest way to “patch” a public skill locally. diff --git a/skills/adapt-yourself/references/ARCHITECTURE.md b/skills/adapt-yourself/references/ARCHITECTURE.md index aeef212..8b3749c 100644 --- a/skills/adapt-yourself/references/ARCHITECTURE.md +++ b/skills/adapt-yourself/references/ARCHITECTURE.md @@ -45,11 +45,9 @@ Common locations: - Project-local: - `/.agents/skills/` - - `/.openhands/skills/` (legacy) - User-global: - `~/.agents/skills/` - - `~/.openhands/skills/` (legacy) - Public registry: - `https://github.com/OpenHands/extensions` (cached locally under `~/.openhands/skills-cache/`) From 5063dcbf3d1b1ed226d10c0dcc5693efb0cc4590 Mon Sep 17 00:00:00 2001 From: openhands Date: Sat, 21 Feb 2026 06:44:40 +0000 Subject: [PATCH 07/19] skills: tighten MCP recommendation criteria Co-authored-by: openhands --- skills/adapt-yourself/SKILL.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/skills/adapt-yourself/SKILL.md b/skills/adapt-yourself/SKILL.md index 19587f7..bcb1e46 100644 --- a/skills/adapt-yourself/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -83,11 +83,14 @@ See: [Hook templates](references/TEMPLATES.md#hookshooksjson-template) and [Hook ### 1.4 Add tools via MCP (`.mcp.json`) -Use when the user wants a **new tool** (capability) that should be available to the agent: -- internal HTTP APIs -- local services -- language servers -- DB query endpoints +Recommend MCP **only when there is a concrete MCP server to add**: + +- The user explicitly asks to “add an MCP server”, **or** +- The user asks for a capability and you can point to an existing MCP server for it (e.g., from that product’s docs / an official MCP server repo). + +If there isn’t an MCP server available for what they want, don’t force MCP: +- start with a **skill** (instructions/workflow), or +- if they truly need a new tool, the real work item is to **build or install an MCP server** (or implement a native tool/code change). MCP server configuration is **product-specific**: From b1d87e30ab36206dda775c66fb1e44fb57542740 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Sat, 21 Feb 2026 07:47:30 +0100 Subject: [PATCH 08/19] Apply suggestion from @enyst --- skills/adapt-yourself/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/adapt-yourself/SKILL.md b/skills/adapt-yourself/SKILL.md index bcb1e46..4d6c15b 100644 --- a/skills/adapt-yourself/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -122,7 +122,6 @@ If you’re not sure, start by reproducing the issue and locating the code path. ## 3) uv development workflows (including `uv tool install openhands`) -Keep this section **high-level**; the goal is to pick the right workflow, not memorize `uv`. - If they run OpenHands from a **local clone**: use `uv sync` + `uv run openhands`. - If they installed OpenHands via **`uv tool install openhands`**: From 11191e7a59a728c120dde1a4f634537489ba34d8 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Sat, 21 Feb 2026 07:47:55 +0100 Subject: [PATCH 09/19] Apply suggestion from @enyst --- skills/adapt-yourself/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/adapt-yourself/SKILL.md b/skills/adapt-yourself/SKILL.md index 4d6c15b..e4c55fc 100644 --- a/skills/adapt-yourself/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -122,7 +122,6 @@ If you’re not sure, start by reproducing the issue and locating the code path. ## 3) uv development workflows (including `uv tool install openhands`) - - If they run OpenHands from a **local clone**: use `uv sync` + `uv run openhands`. - If they installed OpenHands via **`uv tool install openhands`**: - safest: `uv tool run --from /path/to/OpenHands-CLI openhands` From 682ba1e9175de9a65c20517af69e7db5e839b803 Mon Sep 17 00:00:00 2001 From: openhands Date: Sat, 21 Feb 2026 06:53:13 +0000 Subject: [PATCH 10/19] skills: fix verification checklist wording Co-authored-by: openhands --- skills/adapt-yourself/SKILL.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/skills/adapt-yourself/SKILL.md b/skills/adapt-yourself/SKILL.md index e4c55fc..e31b300 100644 --- a/skills/adapt-yourself/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -132,19 +132,19 @@ Details: [Installation modes (`uv tool` vs `uv run`)](references/INSTALLATION_MO ## 4) What requires a restart to take effect? -- **Skills / AGENTS.md**: typically loaded at conversation start → restart the app/CLI (or start a new conversation) to guarantee reload. -- **Hooks (.openhands/hooks.json)**: loaded when the agent/conversation initializes → restart to guarantee reload. -- **Plugins**: loaded when the conversation initializes → restart to guarantee reload. -- **Editable Python code (uv tool `--editable` or local `uv run`)**: changes apply the next time the Python process starts. +- **Skills / AGENTS.md**: loaded at conversation start → usually **start a new conversation** to pick them up. Ask the user to fully restart OpenHands only if needed. +- **Hooks (.openhands/hooks.json)**: loaded when the agent/conversation initializes → ask the user to restart (or create a fresh session) to guarantee reload. +- **Plugins**: loaded when the conversation initializes → ask the user to restart (or create a fresh session) to guarantee reload. +- **Editable Python code (uv tool `--editable` or local `uv run`)**: changes apply the next time the Python process starts → ask the user to restart the CLI/app. ## 5) Verification checklist -After making a “self-modification” change: +After making a “self-modification” change, guide the **user** through verification: -1. Restart OpenHands. -2. In the CLI, run `/skills` to confirm the expected skills/hooks/MCPs are loaded. -3. Trigger the workflow with a tiny, deterministic test prompt. -4. If it’s a code change, run the smallest relevant test suite (or add one). +1. Ask the user to start a **fresh conversation** (and restart OpenHands only if needed). +2. If they’re using the **OpenHands CLI TUI**, ask them to type `/skills` to confirm the expected skills/hooks/MCPs are loaded. +3. Ask the user to send a tiny, deterministic **test prompt** that should trigger the new behavior. +4. If it’s a code change, run the smallest relevant test suite (or ask the user to run it) and confirm the behavior matches. ## References From 79fc77ccb6a9a623449d42174b18c7a71ce0869c Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Sat, 21 Feb 2026 07:55:43 +0100 Subject: [PATCH 11/19] Apply suggestion from @enyst --- skills/adapt-yourself/references/ARCHITECTURE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/adapt-yourself/references/ARCHITECTURE.md b/skills/adapt-yourself/references/ARCHITECTURE.md index 8b3749c..4a6fd2c 100644 --- a/skills/adapt-yourself/references/ARCHITECTURE.md +++ b/skills/adapt-yourself/references/ARCHITECTURE.md @@ -29,7 +29,7 @@ This repo is a **uv workspace** that produces multiple packages: - plugin loader - `openhands-tools` (module: `openhands.tools`) - - built-in tools used by many OpenHands products + - built-in tools used by many OpenHands projects - `openhands-workspace` (module: `openhands.workspace`) - workspace mounting, file sync abstractions From 4e5e8caeb5a06cc73b88d476b2e70cbe3b1d1f23 Mon Sep 17 00:00:00 2001 From: openhands Date: Sat, 21 Feb 2026 06:57:14 +0000 Subject: [PATCH 12/19] skills: prefer projects over products wording Co-authored-by: openhands --- skills/adapt-yourself/SKILL.md | 4 ++-- skills/adapt-yourself/references/ARCHITECTURE.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/adapt-yourself/SKILL.md b/skills/adapt-yourself/SKILL.md index e31b300..1c14ac2 100644 --- a/skills/adapt-yourself/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -86,13 +86,13 @@ See: [Hook templates](references/TEMPLATES.md#hookshooksjson-template) and [Hook Recommend MCP **only when there is a concrete MCP server to add**: - The user explicitly asks to “add an MCP server”, **or** -- The user asks for a capability and you can point to an existing MCP server for it (e.g., from that product’s docs / an official MCP server repo). +- The user asks for a capability and you can point to an existing MCP server for it (e.g., from that project’s docs / an official MCP server repo). If there isn’t an MCP server available for what they want, don’t force MCP: - start with a **skill** (instructions/workflow), or - if they truly need a new tool, the real work item is to **build or install an MCP server** (or implement a native tool/code change). -MCP server configuration is **product-specific**: +MCP server configuration is **project-specific**: - **OpenHands-CLI** persists MCP servers in `~/.openhands/mcp.json` (or `$OPENHANDS_PERSISTENCE_DIR/mcp.json`). - **Software Agent SDK skills/plugins** use a **per-skill/per-plugin** `.mcp.json` file located inside the skill/plugin directory. diff --git a/skills/adapt-yourself/references/ARCHITECTURE.md b/skills/adapt-yourself/references/ARCHITECTURE.md index 4a6fd2c..1dc140b 100644 --- a/skills/adapt-yourself/references/ARCHITECTURE.md +++ b/skills/adapt-yourself/references/ARCHITECTURE.md @@ -61,7 +61,7 @@ Skill types: Hooks are configured via JSON and executed on events (e.g. `pre_tool_use`). -Typical locations (depending on product / SDK config): +Typical locations (depending on project / SDK config): - `/.openhands/hooks.json` - `~/.openhands/hooks.json` @@ -98,4 +98,4 @@ Plugins can be: MCP servers provide tool endpoints to the agent. -They are configured via `.mcp.json` (location depends on host product). Plugins can also provide MCP config. +They are configured via `.mcp.json` (location depends on host project). Plugins can also provide MCP config. From 5d5e6e3495c7eff5009071675a36201a56c0c4c4 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Sat, 21 Feb 2026 08:04:10 +0100 Subject: [PATCH 13/19] Apply suggestion from @enyst --- skills/adapt-yourself/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/skills/adapt-yourself/SKILL.md b/skills/adapt-yourself/SKILL.md index 1c14ac2..0f52686 100644 --- a/skills/adapt-yourself/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -6,6 +6,7 @@ triggers: - change your behavior - customize openhands - self-modify +- adapt yourself - self modification - hack openhands - .agents/skills From 617e03c636238df3e0c3cca9623dc7b157a48509 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Mon, 23 Feb 2026 20:57:09 +0100 Subject: [PATCH 14/19] Remove duplicate entries in marketplace.json --- .plugin/marketplace.json | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.plugin/marketplace.json b/.plugin/marketplace.json index 48736b3..71e6f94 100644 --- a/.plugin/marketplace.json +++ b/.plugin/marketplace.json @@ -236,9 +236,7 @@ "customization", "skills", "hooks", - "plugins", - "mcp", - "uv" + "plugins" ] }, { From 621837e1b80b6a9648fc3f3fef9e557fdcc41d65 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Mon, 23 Feb 2026 21:59:50 +0100 Subject: [PATCH 15/19] Apply suggestion from @enyst --- skills/adapt-yourself/references/TEMPLATES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/adapt-yourself/references/TEMPLATES.md b/skills/adapt-yourself/references/TEMPLATES.md index 21bc4c9..643ca4d 100644 --- a/skills/adapt-yourself/references/TEMPLATES.md +++ b/skills/adapt-yourself/references/TEMPLATES.md @@ -4,7 +4,7 @@ Use these as starting points when implementing a “self-modification” without ## AgentSkills (`SKILL.md`) template -Create a directory: +If you decide an Agentskill is appropriate for user's request to remember or adapt to their needs, you can create it. First, create a directory: ``` /.agents/skills// From 4486ece73b12543b7c5fc1e98f2972dc1e6d7b15 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Mon, 23 Feb 2026 22:01:49 +0100 Subject: [PATCH 16/19] Apply suggestion from @enyst --- skills/adapt-yourself/references/TEMPLATES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/adapt-yourself/references/TEMPLATES.md b/skills/adapt-yourself/references/TEMPLATES.md index 643ca4d..0937d65 100644 --- a/skills/adapt-yourself/references/TEMPLATES.md +++ b/skills/adapt-yourself/references/TEMPLATES.md @@ -62,7 +62,7 @@ Create `/AGENTS.md`: ## Hooks (`.openhands/hooks.json`) template -Create `/.openhands/hooks.json`: +If you decide a Hook is appropriate for addressing the user's request to adapt for next time, you can create a hook. Create or use `/.openhands/hooks.json`: ```json { From 6f7b4d0df9c418c8ce7b5b1b1c9e971c92a84dc8 Mon Sep 17 00:00:00 2001 From: enyst Date: Tue, 24 Feb 2026 08:46:21 +0000 Subject: [PATCH 17/19] fix: narrow adapt-yourself triggers and clarify MCP wording Co-authored-by: openhands --- skills/adapt-yourself/SKILL.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/skills/adapt-yourself/SKILL.md b/skills/adapt-yourself/SKILL.md index 0f52686..febd1fe 100644 --- a/skills/adapt-yourself/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -4,7 +4,6 @@ description: Decide how to make OpenHands adapt/improve itself persistently (aft triggers: - modify yourself - change your behavior -- customize openhands - self-modify - adapt yourself - self modification @@ -93,7 +92,7 @@ If there isn’t an MCP server available for what they want, don’t force MCP: - start with a **skill** (instructions/workflow), or - if they truly need a new tool, the real work item is to **build or install an MCP server** (or implement a native tool/code change). -MCP server configuration is **project-specific**: +MCP server configuration location **depends on the runtime**: - **OpenHands-CLI** persists MCP servers in `~/.openhands/mcp.json` (or `$OPENHANDS_PERSISTENCE_DIR/mcp.json`). - **Software Agent SDK skills/plugins** use a **per-skill/per-plugin** `.mcp.json` file located inside the skill/plugin directory. From f90e5cdb59b9f8e34368b4522ac268e55477cc24 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Tue, 24 Feb 2026 22:34:16 +0100 Subject: [PATCH 18/19] Apply suggestion from @enyst --- skills/adapt-yourself/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/adapt-yourself/SKILL.md b/skills/adapt-yourself/SKILL.md index febd1fe..bca9b5c 100644 --- a/skills/adapt-yourself/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -18,7 +18,7 @@ triggers: When a user says things like “modify yourself to do X” or “remember this next time”, **don’t jump to editing Python code**. OpenHands has multiple extensibility layers; choose the *smallest*, *safest*, and *most persistent* mechanism that matches the user’s intent. -This skill is about **persistent** changes that should still apply after the user restarts the CLI / app. +This skill is about **persistent** changes that should still apply after the user reloads or restarts the CLI / app. If the user wants behavior only for the current conversation, you don't need the mechanisms in this skill—just follow their instructions directly in this session. ## 0) First: clarify what kind of change the user wants From 5592fcec8fc1540ae3922696e7d62f641beba61d Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Tue, 24 Feb 2026 22:34:37 +0100 Subject: [PATCH 19/19] Apply suggestion from @enyst --- skills/adapt-yourself/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/adapt-yourself/SKILL.md b/skills/adapt-yourself/SKILL.md index bca9b5c..0d6a2b3 100644 --- a/skills/adapt-yourself/SKILL.md +++ b/skills/adapt-yourself/SKILL.md @@ -25,7 +25,6 @@ This skill is about **persistent** changes that should still apply after the use Clarify the **scope** and **type** of the change (skip questions the user already answered): 1. **Persistence scope**: Should this change apply… - - only in *this* conversation? - for this *repository/workspace*? - for *all repos on this machine* (user-global)? - for *everyone* (contribution upstream / extensions registry)?