How OpenHands Agent Skills Replace Repeated Prompts With Team-Level Workflows

If you have used OpenHands, Claude Code, or any CLI-based coding agent for more than a week, you have probably noticed the tax: every new session, you retype the same instructions. "Follow our PR format," "use Black with 88-char limit," "write Google-style docstrings." The agent does not remember. You paste. Again. OpenHands has a direct answer to this: agent skills. They are not a workaround or a config hack — they are a proper abstraction for making repetitive, spec-driven workflows reusable across every session and every developer on your team.

What an Agent Skill Actually Is#

An OpenHands agent skill is a structured knowledge package that extends a coding agent with domain-specific instructions. Skills follow the AgentSkills standard — a format designed to let agents load relevant context on demand, rather than loading every possible instruction upfront. A skill lives in a directory with this structure:

my-skill/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

The key piece is SKILL.md. It has a YAML frontmatter block that defines the skill name, a description the agent reads to decide when to load it, and trigger phrases. Below that, it is plain markdown with whatever instructions you need the agent to follow.

How OpenHands loads skills matters here: only the metadata sits in context by default. The full instructions are loaded only when a trigger matches. The OpenHands team calls this progressive disclosure — it keeps the agent's context clean and reduces token overhead for tasks that have nothing to do with a particular skill.

Writing a SKILL.md That Works#

Here is a real example. Suppose your team has a Python review checklist for every PR: Black formatting, Ruff linting, Google-style docstrings, type hints on all public APIs, and pytest coverage for any new functions.

---
name: python-review
description: Use when reviewing Python code, checking Python style, running lint,
  or when the user mentions code quality on a Python project.
triggers:
  - python review
  - lint python
  - code quality check
  - check python style
---

# Python Code Review Workflow

Run the following checks in order on the specified Python files or PR diff:

1. Black formatting — 88-char line limit: `black --check --line-length 88 .`
2. Ruff linting with project rules: `ruff check . --config pyproject.toml`
3. Verify type hints exist on all public functions and methods
4. Confirm docstrings follow Google style (Args, Returns, Raises sections)
5. If new functions were added, confirm corresponding pytest coverage exists

Report each failure with file name, line number, and a one-line fix suggestion.
Do not auto-fix — report only, and wait for confirmation before applying changes.

Drop this into .openhands/skills/ or .agents/skills/ in your repo. Now when any developer types "review this Python code," the agent loads the full workflow automatically. No paste, no reminder, no drift.

Three things that determine whether this actually works:

Specificity beats vagueness. "Follow our code standards" gives the agent nothing concrete. Step-by-step commands with flags and expected outputs do. The agent cannot invent your standards from vague instructions.

Scope triggers tightly. Broad triggers like "check code" will load this skill on unrelated questions. The description field is the agent's decision-making guide — write it as if you are telling a human expert exactly when they should be called in, not just what they know.

Separate reporting from fixing. The example above explicitly says "report only, wait for confirmation." This is the right default for any skill touching production code. If the agent auto-fixes and the fix is wrong, you now have two problems. Confirmation gates cost thirty seconds; silent auto-fixes cost hours of debugging.

Deploying Skills to Your Team#

Skills have three deployment paths depending on your scope:

Repository-local: Add the skill directory to .agents/skills/ in your repo. Every developer using OpenHands in that project has the skill available automatically. This is the right default for team standards — the skill lives in version control alongside the code it governs.

Shared via GitHub: Any skill hosted on GitHub can be added with /add-skill https://github.com/yourorg/skill-repo. This works well for org-wide skills that apply across multiple repos, like your internal review standards or a Datadog integration skill.

Published to the OpenHands extensions registry: If you have built something generic — a Docker debugging skill, a release notes generator, a Vercel deployment skill — you can publish it so the broader community can use it. OpenHands already ships a default extensions set covering GitHub, GitLab, Azure DevOps, Bitbucket, Discord, and more.

For CI/CD integration, OpenHands provides a GitHub Actions plugin for the PR review workflow. You configure it to trigger when a PR moves to "ready for review," and the agent applies the skill without anyone typing anything. That is where skills shift from a developer productivity tool to a team enforcement mechanism — every PR gets reviewed against the same checklist, no exceptions, no human bottleneck. For context on structuring those pipelines safely, the GitHub CI/CD agentic setups covered on this site are worth reading first.

This also connects directly to the problem of managing the AI code review flood — skills are one of the more disciplined answers to keeping AI-generated reviews from becoming noise rather than signal.

Where Skills Break Down#

A few failure modes worth planning for before deploying anything beyond a personal workflow:

Vague SKILL.md equals inconsistent output. If your instructions say "write clean code," the agent fills that gap with its own definition of clean. If your instructions say "run Black with --line-length 88 and report failures by file and line number," the agent has a concrete target. Vague instructions produce plausibly-shaped results that quietly diverge from your actual standards.

Trigger collisions. If two skills have similar triggers or overlapping descriptions, the agent may load the wrong one. Keep each skill's description distinct and specific. Test skill triggering in isolation before deploying to CI — a skill that fires unexpectedly in an automated pipeline is worse than no skill at all.

Progressive disclosure has a token cost. The full instructions load only on trigger — but if a skill is triggered unexpectedly on a long session, the added context size matters. Keep skill instructions tight. A 2,000-word SKILL.md for a task that needs 200 words is a sign the skill should be split.

Skills do not replace evaluation. A skill codifies a workflow. It does not guarantee the agent follows it correctly every time. OpenHands recommends logging agent behavior via OpenTelemetry-compatible hooks and tracking metrics like suggestion acceptance rate. This monitoring layer connects naturally to MCP-powered agent workflows, where external tool integration adds observability without additional custom code.

Team adoption requires visibility. If skills live in .agents/skills/ but your team does not know they exist, no one will use them. Document them in your engineering wiki. Add a README in the skills directory. List the trigger phrases somewhere developers will find them. A skill that goes undiscovered is wasted maintenance work.

What I Would Do#

If you are evaluating whether skills are worth investing time in: start with one workflow you already have documented. Your PR checklist, your commit message format, your dependency upgrade runbook. Convert it into a SKILL.md, deploy it locally, run it five times on real work, and track how often the agent hits the mark.

OpenHands ships a skill-creator skill specifically for this: after completing a workflow manually, invoking /skill-creator generates the SKILL.md based on what the agent just did. That is a better starting point than writing from scratch, because the agent already has context about what a successful run looks like and can encode the specifics rather than guessing at them.

Do not try to skill-ify everything upfront. The workflows worth automating are the ones you can describe with a checklist and a command. The ones that require judgment every time — architecture decisions, design review, anything where "it depends" is genuinely the right answer — do not compress well into a SKILL.md and should stay in human hands.

If you are comparing approaches, the skills model in OpenHands takes a similar intent to how Gemini CLI approaches subagent delegation, but makes the packaging, discovery, and triggering explicit rather than relying on prompt construction at runtime. That tradeoff favors OpenHands when you need team consistency; it favors dynamic prompting when tasks are more ad-hoc.

The Maintenance Obligation#

OpenHands agent skills solve a real, boring problem: coding agents are stateless, and stateless agents do not scale to teams. Skills trade that statelessness for a structured, version-controlled, reviewable document that defines how your agent should behave.

The format is simple enough to write in an afternoon. The deployment is lightweight — a directory in your repo. The payoff, when instructions are specific, is genuine consistency across reviews, tasks, and developers.

The harder part is maintenance. Instructions go stale when codebases evolve. Build a habit of updating SKILL.md when your standards change, and treat skill evaluation metrics as part of your engineering health checks. That discipline is what separates a useful skill from a source of confusion three months later.