fix: revert flat SKILL.md support, load proper plugins from anthropics/skills

The previous changes added support for 'flat' SKILL.md format where a single
AgentSkill directory was treated as a plugin. Per discussion in #2272, this
conflates AgentSkills with Plugins and creates confusion.

Changes:
- Revert _load_skills() to only check skills/ subdirectory (no root fallback)
- Remove flat SKILL.md tests from test_installed_plugins.py
- Update example script and tests to load full anthropics/skills repository
  which contains proper plugins with skills/ subdirectories (document-skills
  plugin with pptx, xlsx, docx, pdf skills)

The anthropics/skills repo marketplace.json lists 'document-skills' and
'example-skills' as the actual plugins, not individual AgentSkill folders.

Co-authored-by: openhands <openhands@all-hands.dev>

Author: openhands-agent

examples/05_skills_and_plugins/02_loading_plugins/main.py

@@ -48,17 +48,19 @@ def demo_conversation_with_github_plugin(llm: LLM) -> None:
 
     This demonstrates loading a plugin directly from GitHub using PluginSource.
     The plugin is fetched and loaded lazily when the conversation starts.
+
+    We load the anthropics/skills repository which contains the "document-skills"
+    plugin with skills for pptx, xlsx, docx, and pdf document processing.
     """
     print("\n" + "=" * 60)
     print("DEMO 1: Loading plugin from GitHub via Conversation")
     print("=" * 60)
 
-    # Load the pptx skill from anthropics/skills repository
-    # This skill helps create PowerPoint presentations
+    # Load the anthropics/skills repository which contains the document-skills plugin
+    # This plugin bundles multiple document processing skills including pptx
     plugins = [
         PluginSource(
             source="github:anthropics/skills",
-            repo_path="skills/pptx",
             ref="main",
         ),
     ]
@@ -76,12 +78,6 @@ def demo_conversation_with_github_plugin(llm: LLM) -> None:
                 plugins=plugins,
             )
 
-            # Ask a question that uses the pptx skill
-            conversation.send_message(
-                "What's the best way to create a PowerPoint presentation "
-                "programmatically? Check the skill before you answer."
-            )
-
             # Verify skills were loaded
             skills = (
                 conversation.agent.agent_context.skills
@@ -92,6 +88,12 @@ def demo_conversation_with_github_plugin(llm: LLM) -> None:
             for skill in skills:
                 print(f"  - {skill.name}")
 
+            # Ask a question that uses the pptx skill
+            conversation.send_message(
+                "What's the best way to create a PowerPoint presentation "
+                "programmatically? Check the skill before you answer."
+            )
+
             conversation.run()
 
         except PluginFetchError as e:
@@ -117,17 +119,17 @@ def demo_install_local_plugin(installed_dir: Path) -> None:
 def demo_install_github_plugin(installed_dir: Path) -> None:
     """Demo 3: Install a plugin from GitHub to persistent storage.
 
-    Demonstrates the github:owner/repo shorthand with repo_path for monorepos.
+    Demonstrates loading the anthropics/skills repository which contains
+    multiple document processing skills (pptx, xlsx, docx, pdf).
     """
     print("\n" + "=" * 60)
     print("DEMO 3: Installing plugin from GitHub")
     print("=" * 60)
 
     try:
-        # Install from anthropics/skills repository
+        # Install the anthropics/skills repository (contains document-skills plugin)
         info = install_plugin(
             source="github:anthropics/skills",
-            repo_path="skills/pptx",
             ref="main",
             installed_dir=installed_dir,
         )
@@ -141,9 +143,11 @@ def demo_install_github_plugin(installed_dir: Path) -> None:
             if plugin.name == info.name:
                 skills = plugin.get_all_skills()
                 print(f"  Skills: {len(skills)}")
-                for skill in skills:
+                for skill in skills[:5]:  # Show first 5 skills
                     desc = skill.description or "(no description)"
                     print(f"    - {skill.name}: {desc[:50]}...")
+                if len(skills) > 5:
+                    print(f"    ... and {len(skills) - 5} more skills")
 
     except PluginFetchError as e:
         print(f"⚠ Could not fetch from GitHub: {e}")

openhands-sdk/openhands/sdk/plugin/plugin.py

@@ -385,52 +385,36 @@ def _load_manifest(plugin_dir: Path) -> PluginManifest:
 
 
 def _load_skills(plugin_dir: Path) -> list[Skill]:
-    """Load skills from the plugin directory.
-
-    Supports two formats:
-    1. SDK format: skills in skills/<name>/SKILL.md subdirectories
-    2. Flat format: single SKILL.md at plugin root (e.g., anthropics/skills)
+    """Load skills from the skills/ directory.
 
     Note: Plugin skills are loaded with relaxed validation (strict=False)
     to support Claude Code plugins which may use different naming conventions.
     """
-    skills: list[Skill] = []
-
-    # Check for skills/ subdirectory (SDK format)
     skills_dir = plugin_dir / "skills"
-    if skills_dir.is_dir():
-        for item in skills_dir.iterdir():
-            if item.is_dir():
-                skill_md = find_skill_md(item)
-                if skill_md:
-                    try:
-                        skill = Skill.load(skill_md, skills_dir, strict=False)
-                        # Discover and attach resources
-                        skill.resources = discover_skill_resources(item)
-                        skills.append(skill)
-                        logger.debug(f"Loaded skill: {skill.name} from {skill_md}")
-                    except Exception as e:
-                        logger.warning(f"Failed to load skill from {item}: {e}")
-            elif item.suffix == ".md" and item.name.lower() != "readme.md":
-                # Also support single .md files in skills/ directory
+    if not skills_dir.is_dir():
+        return []
+
+    skills: list[Skill] = []
+    for item in skills_dir.iterdir():
+        if item.is_dir():
+            skill_md = find_skill_md(item)
+            if skill_md:
                 try:
-                    skill = Skill.load(item, skills_dir, strict=False)
+                    skill = Skill.load(skill_md, skills_dir, strict=False)
+                    # Discover and attach resources
+                    skill.resources = discover_skill_resources(item)
                     skills.append(skill)
-                    logger.debug(f"Loaded skill: {skill.name} from {item}")
+                    logger.debug(f"Loaded skill: {skill.name} from {skill_md}")
                 except Exception as e:
                     logger.warning(f"Failed to load skill from {item}: {e}")
-
-    # Fallback: check for root-level SKILL.md (flat format, e.g., anthropics/skills)
-    if not skills:
-        root_skill_md = find_skill_md(plugin_dir)
-        if root_skill_md:
+        elif item.suffix == ".md" and item.name.lower() != "readme.md":
+            # Also support single .md files in skills/ directory
             try:
-                skill = Skill.load(root_skill_md, plugin_dir, strict=False)
-                skill.resources = discover_skill_resources(plugin_dir)
+                skill = Skill.load(item, skills_dir, strict=False)
                 skills.append(skill)
-                logger.debug(f"Loaded root skill: {skill.name} from {root_skill_md}")
+                logger.debug(f"Loaded skill: {skill.name} from {item}")
             except Exception as e:
-                logger.warning(f"Failed to load root skill from {root_skill_md}: {e}")
+                logger.warning(f"Failed to load skill from {item}: {e}")
 
     return skills
 

tests/sdk/plugin/test_installed_plugins.py

@@ -470,100 +470,6 @@ def test_update_nonexistent_plugin(installed_dir: Path) -> None:
     assert info is None
 
 
-# ============================================================================
-# Root-Level SKILL.md Tests (flat format support)
-# ============================================================================
-
-
-def test_load_plugin_with_root_skill_md(tmp_path: Path) -> None:
-    """Test loading a plugin with SKILL.md at the root (flat format).
-
-    This tests support for the anthropics/skills format where SKILL.md
-    is at the plugin root instead of in a skills/ subdirectory.
-    """
-    plugin_dir = tmp_path / "flat-plugin"
-    plugin_dir.mkdir(parents=True)
-
-    # Create plugin manifest
-    (plugin_dir / ".plugin").mkdir()
-    (plugin_dir / ".plugin" / "plugin.json").write_text(
-        json.dumps(
-            {
-                "name": "flat-plugin",
-                "version": "1.0.0",
-                "description": "A flat-format plugin",
-            }
-        )
-    )
-
-    # Create SKILL.md at root (not in skills/ subdirectory)
-    (plugin_dir / "SKILL.md").write_text(
-        """---
-name: flat-skill
-description: A skill at the root level
----
-# Flat Skill
-
-This skill is at the plugin root, not in skills/ subdirectory.
-"""
-    )
-
-    # Load the plugin
-    plugin = Plugin.load(plugin_dir)
-
-    assert plugin.name == "flat-plugin"
-    skills = plugin.get_all_skills()
-    assert len(skills) == 1
-    assert skills[0].name == "flat-skill"
-
-
-def test_load_plugin_prefers_skills_dir_over_root(tmp_path: Path) -> None:
-    """Test that skills/ directory takes precedence over root SKILL.md."""
-    plugin_dir = tmp_path / "mixed-plugin"
-    plugin_dir.mkdir(parents=True)
-
-    # Create plugin manifest
-    (plugin_dir / ".plugin").mkdir()
-    (plugin_dir / ".plugin" / "plugin.json").write_text(
-        json.dumps(
-            {
-                "name": "mixed-plugin",
-                "version": "1.0.0",
-                "description": "Plugin with both formats",
-            }
-        )
-    )
-
-    # Create SKILL.md at root
-    (plugin_dir / "SKILL.md").write_text(
-        """---
-name: root-skill
-description: Skill at root
----
-Root skill content.
-"""
-    )
-
-    # Create skill in skills/ subdirectory
-    skills_dir = plugin_dir / "skills" / "nested-skill"
-    skills_dir.mkdir(parents=True)
-    (skills_dir / "SKILL.md").write_text(
-        """---
-name: nested-skill
-description: Skill in skills/ directory
----
-Nested skill content.
-"""
-    )
-
-    # Load the plugin - should prefer skills/ directory
-    plugin = Plugin.load(plugin_dir)
-
-    skills = plugin.get_all_skills()
-    assert len(skills) == 1
-    assert skills[0].name == "nested-skill"  # Not root-skill
-
-
 # ============================================================================
 # Integration Tests (Real GitHub)
 # ============================================================================
@@ -619,39 +525,48 @@ def test_install_from_github_with_ref(installed_dir: Path) -> None:
 
 
 @pytest.mark.network
-def test_install_from_anthropic_skills(installed_dir: Path) -> None:
-    """Test installing a skill from anthropics/skills repository.
+def test_install_document_skills_plugin(installed_dir: Path) -> None:
+    """Test installing the document-skills plugin from anthropics/skills repository.
 
-    This tests the Claude Code skill format where SKILL.md is at the root.
-    The SDK should detect and load the root-level SKILL.md as the plugin's skill.
+    This tests loading a proper Claude Code plugin which bundles multiple skills
+    (xlsx, docx, pptx, pdf) in the skills/ subdirectory.
     """
     try:
         info = install_plugin(
             source="github:anthropics/skills",
-            repo_path="skills/pptx",
             ref="main",
             installed_dir=installed_dir,
         )
 
-        assert info.name == "pptx"
+        assert info.name == "anthropic-agent-skills"
         assert info.source == "github:anthropics/skills"
-        assert info.repo_path == "skills/pptx"
 
+        # Verify the plugin directory has the expected structure
         install_path = Path(info.install_path)
-        skill_md = install_path / "SKILL.md"
-        assert skill_md.exists()
+        skills_dir = install_path / "skills"
+        assert skills_dir.is_dir()
 
-        content = skill_md.read_text()
-        assert "name: pptx" in content
-        assert "description:" in content
+        # Check that the expected skill directories exist
+        for skill_name in ["pptx", "xlsx", "docx", "pdf"]:
+            skill_dir = skills_dir / skill_name
+            assert skill_dir.is_dir(), f"Expected skill directory: {skill_name}"
+            skill_md = skill_dir / "SKILL.md"
+            assert skill_md.exists(), f"Expected SKILL.md in {skill_name}"
 
-        # Verify the skill is loaded (tests root-level SKILL.md support)
+        # Verify skills are loaded from the plugin
         plugins = load_installed_plugins(installed_dir=installed_dir)
-        pptx_plugin = next((p for p in plugins if p.name == "pptx"), None)
-        assert pptx_plugin is not None
-        skills = pptx_plugin.get_all_skills()
-        assert len(skills) == 1
-        assert skills[0].name == "pptx"
+        doc_plugin = next(
+            (p for p in plugins if p.name == "anthropic-agent-skills"), None
+        )
+        assert doc_plugin is not None
+        skills = doc_plugin.get_all_skills()
+        # Should have at least the 4 document skills
+        assert len(skills) >= 4
+        skill_names = {s.name for s in skills}
+        assert "pptx" in skill_names
+        assert "xlsx" in skill_names
+        assert "docx" in skill_names
+        assert "pdf" in skill_names
 
     except PluginFetchError:
         pytest.skip("GitHub not accessible (network issue)")