docs: add AGENTS.md and refresh README

AGENTS.md

@@ -0,0 +1,71 @@
+# OpenHands Skills Registry — Agent Notes
+
+This repository (`OpenHands/skills`) is the **public skills registry** for OpenHands.
+It contains **shareable skills** that can be loaded by OpenHands (CLI/GUI/Cloud) and by client code using the **Software Agent SDK**.
+
+## What this repo contains
+
+- `skills/` — a catalog of skills, **one directory per skill**.
+  - `skills/<skill-name>/SKILL.md` — the skill definition (AgentSkills-style progressive disclosure)
+  - `skills/<skill-name>/README.md` — optional extra docs/examples for humans
+
+There is no application code here; the primary artifacts are Markdown skill definitions.
+
+## How client code uses this repo
+
+### OpenHands (product)
+
+OpenHands can load skills from a project directory (repo-level) and from user-level locations.
+This repository is the **global/public** registry referenced by the docs.
+
+### Software Agent SDK
+
+SDK consumers typically load skills either:
+
+- as **always-loaded context** (e.g., `AGENTS.md`), and/or
+- as **progressive-disclosure AgentSkills** by discovering `SKILL.md` files under a directory.
+
+See: https://docs.openhands.dev/sdk/guides/skill
+
+## AgentSkills / Skill authoring rules (follow these)
+
+OpenHands supports an extended version of the **AgentSkills** standard (https://agentskills.io/specification).
+When editing or adding skills in this repo, follow these rules:
+
+1. **One skill per directory**
+   - Create `skills/<skill-name>/SKILL.md`.
+   - Keep the directory name stable; it is used as the skill identifier/location.
+
+2. **SKILL.md should be progressive disclosure**
+   - Put a concise summary/description first.
+   - Include only the information needed for an agent to decide whether to open/read the skill.
+   - If the skill needs large references, keep them in the same directory (e.g., `references/`) and point to them.
+
+3. **Be specific and operational**
+   - Prefer checklists, steps, and concrete examples.
+   - Avoid vague guidance like “be careful” without actionable criteria.
+
+4. **Avoid repo-local assumptions**
+   - Skills here are **public and reusable**.
+   - Don’t reference private paths, secrets, or company-specific URLs.
+
+5. **Do not include secrets or sensitive data**
+   - Never commit API keys, tokens, credentials, private endpoints, or internal customer data.
+
+6. **Prefer minimal, composable skills**
+   - Keep a skill focused on a single domain/task.
+   - If it grows large, split it into multiple skills.
+
+7. **Compatibility notes**
+   - The legacy `.openhands/microagents/` location may still exist in user repos, but this registry uses the current skills layout.
+
+## Repository conventions
+
+- Keep formatting consistent across skills.
+- If you change a skill’s behavior or scope, update its `README.md` (if present) accordingly.
+- If you change top-level documentation, ensure links still resolve.
+
+## When uncertain
+
+- Prefer the official OpenHands docs on skills: https://docs.openhands.dev/overview/skills
+- Prefer the SDK skill guide: https://docs.openhands.dev/sdk/guides/skill

README.md

@@ -1,73 +1,28 @@
 # OpenHands Skills Registry
 
-Public registry of **Skills** for [OpenHands](https://github.com/OpenHands/OpenHands) - reusable guidelines that customize agent behavior.
-Check the [documentation](https://docs.openhands.dev/overview/skills) for more information.
+This repository is the **public skill registry** for [OpenHands](https://github.com/OpenHands/OpenHands).
+It contains reusable, shareable skills that customize agent behavior.
 
-> **Note**: Skills were previously called Microagents. The `.openhands/microagents/` folder path still works for backward compatibility.
+- Skills overview docs: https://docs.openhands.dev/overview/skills
+- SDK skill guide: https://docs.openhands.dev/sdk/guides/skill
 
-## What are Skills?
+## Repository layout
 
-Skills are Markdown files containing instructions and best practices that guide OpenHands agents. They provide domain expertise (git, docker, kubernetes), encode best practices (code review, security), and eliminate repetitive instructions.
+Skills live under `skills/`, **one directory per skill**:
 
-## Skill Types
+- `skills/<skill-name>/SKILL.md` — the skill definition (AgentSkills-style progressive disclosure)
+- `skills/<skill-name>/README.md` — optional human-facing notes/examples
 
-### General Skills
-Always loaded as context. No frontmatter needed.
-
-```markdown
-# Repository Guidelines
-This project uses React and Node.js. Run `npm install` to set up...
-```
-
-### Keyword-Triggered Skills
-Loaded only when trigger words appear in user prompts. Requires frontmatter.
-
-```markdown
----
-triggers:
-  - docker
-  - dockerfile
----
-
-# Docker Guidelines
-When working with Docker containers...
-```
+Browse the catalog in [`skills/`](skills/).
 
 ## Contributing
 
-To contribute a skill:
-
 1. Fork this repository
-2. Add a `.md` file in the `skills/` directory
-3. For keyword-triggered skills, include frontmatter with `triggers` list
-4. Submit a pull request
-
-**Good skills are:**
-- Specific and actionable
-- Focused on a single domain or task
-- Include concrete examples
-- Use relevant trigger keywords (for keyword-triggered skills)
-
-## Frontmatter Reference
-
-**General Skills**: No frontmatter needed
-
-**Keyword-Triggered Skills**: Frontmatter required to specify triggers
-```yaml
----
-triggers:
-  - keyword1
-  - keyword2
-agent: CodeActAgent  # Optional, defaults to CodeActAgent
----
-```
-
-## Examples
-
-See the [`skills/`](skills/) directory for examples like [`github.md`](skills/github.md), [`docker.md`](skills/docker.md), [`code-review.md`](skills/code-review.md).
+2. Create a new directory: `skills/<your-skill-name>/`
+3. Add `skills/<your-skill-name>/SKILL.md`
+4. (Optional) Add `README.md`, `references/`, `scripts/`, etc.
+5. Submit a pull request
 
-## Learn More
+## Agent instructions for working in this repo
 
-- [OpenHands Documentation](https://docs.openhands.dev)
-- [OpenHands Repository](https://github.com/OpenHands/OpenHands)
-- [Software Agent SDK](https://github.com/OpenHands/software-agent-sdk)
+See [`AGENTS.md`](AGENTS.md) for the rules agents should follow when editing/adding skills.