From 6ebeb8d5676907c35315249ac76c92d0f99b9b36 Mon Sep 17 00:00:00 2001
From: chenhz01 <shanlun2029@outlook.com>
Date: Thu, 17 Sep 2026 01:33:49 +0800
Subject: [PATCH] docs: document plugin-bundle layout for large collection
 import via Add Repository

---
 overview/skills.mdx | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/overview/skills.mdx b/overview/skills.mdx
index 0526cf44..f227313d 100644
--- a/overview/skills.mdx
+++ b/overview/skills.mdx
@@ -48,6 +48,39 @@ Always-on content occupies the conversation context from the beginning. Keep `AG
 The official global skill registry is maintained at [github.com/OpenHands/extensions](https://github.com/OpenHands/extensions). This repository contains community-shared skills that can be used by all OpenHands agents. You can browse available skills, contribute your own, and learn from examples created by the community.
 
 
+## Importing Large Collections via Add Repository
+
+Settings → Skills → Add Repository registers a GitHub repository as a plugin marketplace. For large skill collections, note that the import path is the **plugin bundle format** — a repository of bare `SKILL.md` folders (even under `.agents/skills/`) currently registers successfully but imports zero skills, with no warning.
+
+A working bundle layout:
+
+```text
+my-skill-library/
+├── .plugin/
+│   └── marketplace.json
+└── plugins/
+    └── my-library/
+        ├── .plugin/
+        │   └── plugin.json
+        └── skills/
+            └── <skill-name>/
+                └── SKILL.md
+```
+
+```json title=".plugin/marketplace.json"
+{
+  "name": "my-skill-library",
+  "owner": { "name": "your-github-username", "email": "you@example.com" },
+  "plugins": [
+    { "name": "my-library", "source": "./plugins/my-library", "description": "..." }
+  ]
+}
+```
+
+<Note>
+After saving, verify the catalog actually lists the imported items. A repository that resolves to zero plugins/skills currently saves silently; start a new conversation after registering so the skill directory is rebuilt. Field-tested at 489 skills / ~2,700 files / 23 MB — see [OpenHands#17278](https://github.com/OpenHands/OpenHands/issues/17278) for the full reproduction.
+</Note>
+
 ## Five-Minute Setup
 
 Add concise repository guidance and one on-demand skill: