docs: document plugin-bundle layout for large collection import via Add Repository

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: