# OpenHands repository skills: migrate older instruction examples

Migrate OpenHands repository instructions into concise AGENTS.md guidance and current Agent Skills locations while separating hooks, setup and tool permissions.

Author: Retrivium team
Updated: 2026-11-03
Canonical URL: https://retrivium.ai/journal/openhands-repository-skills-current-layout/
Language: en

Older OpenHands examples often refer to microagents or repository-specific setup scripts. Current documentation distinguishes repository guidance, portable skills and executable hooks. Migrating an old example should preserve what each piece does, rather than moving every instruction into one large file and assuming the runtime will interpret it in the same way.

## Start with repository-wide guidance

The [General Skills guide](https://docs.openhands.dev/overview/skills/repo) describes concise repository information such as purpose, setup, layout and checks. Put guidance needed for ordinary work in a root `AGENTS.md`. Keep it accurate to the repository instead of copying an unrelated example's commands.

For a project with generated clients, identify the actual source of generation and the relevant verification command. A useful instruction tells the agent where to work and how a person can check the result. It should not become a substitute for keeping the repository's ordinary documentation current.

## Put focused knowledge in current skill locations

The [Skills overview](https://docs.openhands.dev/overview/skills) recommends `.agents/skills/<skill-name>/SKILL.md` for focused Agent Skills. Name and description support discovery; the full instructions and supporting resources are loaded when needed. Always-on guidance and an on-demand workflow have different context costs.

The same overview states that legacy `.openhands/skills/` and `.openhands/microagents/` locations remain supported. Therefore, migration is not justified by claiming those directories have simply stopped working. The benefit is a clearer portable layout and explicit loading behavior for new material.

## Match the trigger to the intended scope

Choose whether guidance applies to every task, a named workflow, a keyword or a file path. OpenHands-specific trigger extensions are not guaranteed to mean the same thing in every Agent Skills client. Keep portability and deterministic activation as separate requirements.

Use a small repository containing a source directory and a documentation directory. Ask for one change in each. Check that a path-specific instruction appears where intended without forcing unrelated implementation steps into the documentation task. Then inspect the proposed diff rather than accepting an assurance that a skill was followed.

## Keep executable preparation and checks separate

The [repository customization guide](https://docs.openhands.dev/openhands/usage/customization/repository) describes `.openhands/setup.sh` and hooks. Instructions that say to install a dependency do not themselves install it. Likewise, asking for tests in a skill does not provide the same enforcement as a configured stop hook.

When updating an older pre-commit example, read the current hook guidance and identify the actual desired gate. Preserve the command's working directory and dependencies. Do not turn a historical snippet into a new repository operation until its behavior is understood for the selected agent-server flow.

## Verify the migrated context in a fresh conversation

The skill documentation recommends a new conversation after file changes so the available-skill catalog is rebuilt. Test the intended task after migration and record the instructions that actually became available. Keep resource paths relative and confirm the required files exist in the backend workspace.

Review permissions independently. A skill can describe a deployment workflow without granting permission to deploy, obtaining credentials or exposing network access. The successful migration is a clear, correctly activated instruction package with supported resources, not a claim that text files can enforce every action the agent takes.

## Related reading

[Reproducible inference stacks: preserving a GPU pilot’s result](/journal/software-stack-reproducibility/), [Coding LLMs on 12GB VRAM: Budget Context and Headroom](/journal/coding-llm-12gb-vram/).