Implement export/install and update examples/tests

Implement bundle and skill export/install functionality and update examples and tests accordingly. Added export_claude_plugin and install_claude_skills implementations on Bundle (writes plugin manifest, skill files, and .musher-managed markers; supports cleaning). Implemented SkillHandle export methods (export_openai_local_skill, export_openai_inline_skill, export_path, export_zip) and added plugin_name to ClaudePluginExport. Updated example scripts to demonstrate Claude/OpenAI usage and adjusted sample bundle refs. Added optional examples dependency (openai-agents) in pyproject.toml. Updated tests to validate the new export/install behaviors and file outputs.

Author: justinmerrell

examples/claude/export_plugin.py

@@ -8,21 +8,39 @@
 
 import musher
 
-# NOTE: Bundle references below (e.g. "acme/agent-toolkit:2.0.0") are
+# NOTE: Bundle references below (e.g. "acme/engineering-workflows:2.0.0") are
 # placeholders. Replace with a real bundle ref from your Musher registry.
 
 # Credentials auto-discovered from MUSHER_API_KEY env var, keyring,
 # or credential file. To override: musher.configure(token="your-token")
 
-bundle = musher.pull("acme/agent-toolkit:2.0.0")
+bundle = musher.pull("acme/engineering-workflows:2.0.0")
 
 # Select only the skills needed for this session
-selection = bundle.select(skills=["csv-insights", "incident-summary"])
+selection = bundle.select(skills=["researching-repos", "drafting-release-notes"])
 
-# PREVIEW: export_claude_plugin() is not yet implemented — will raise NotImplementedError.
-plugin = selection.export_claude_plugin("safe-tools", dest=Path("./plugins"))
+# Export as a local Claude plugin with a namespaced plugin name.
+# Skills will be accessible as "team-workflows:researching-repos", etc.
+plugin = selection.export_claude_plugin("team-workflows", dest=Path("./plugins"))
 print(f"Plugin exported to: {plugin.path}")
 
 # Verify only the selected skills are present
 for skill in selection.skills():
     print(f"  Skill: {skill.name} — {skill.description}")
+
+# To load this plugin with the Claude Agent SDK:
+#
+#   from claude_agent_sdk import ClaudeAgentOptions, query
+#
+#   options = ClaudeAgentOptions(
+#       cwd=str(Path(__file__).resolve().parents[1]),
+#       plugins=[{"type": "local", "path": str(plugin.path)}],
+#       allowed_tools=["Skill", "Read", "Grep", "Glob", "Bash"],
+#       max_turns=3,
+#   )
+#
+#   async for message in query(
+#       prompt="What custom commands do you have available?",
+#       options=options,
+#   ):
+#       ...

examples/claude/install_project_skills.py

@@ -8,23 +8,39 @@
 
 import musher
 
-# NOTE: Bundle references below (e.g. "acme/agent-toolkit:2.0.0") are
+# NOTE: Bundle references below (e.g. "acme/engineering-workflows:2.0.0") are
 # placeholders. Replace with a real bundle ref from your Musher registry.
 
 # Credentials auto-discovered from MUSHER_API_KEY env var, keyring,
 # or credential file. To override: musher.configure(token="your-token")
 
-bundle = musher.pull("acme/agent-toolkit:2.0.0")
+bundle = musher.pull("acme/engineering-workflows:2.0.0")
 
-# Install all skills to the project-level Claude skills directory
-skills_dir = Path(".claude/skills")
-
-# PREVIEW: install_claude_skills() is not yet implemented — will raise NotImplementedError.
+# Install specific skills to the project-level Claude skills directory.
 # clean=True removes stale Musher-managed skill installs for this bundle
 # from the target directory. It does NOT affect unrelated user-managed skills.
-bundle.install_claude_skills(skills_dir, clean=True)
+skills_dir = Path(".claude/skills")
+bundle.install_claude_skills(
+    skills_dir,
+    skills=["researching-repos", "drafting-release-notes"],
+    clean=True,
+)
 
-print(f"Installed {len(bundle.skills())} skills to {skills_dir}")
+print(f"Installed skills to {skills_dir}")
 for skill in bundle.skills():
     print(f"  {skill.name}: {skill.description}")
     print(f"    Files: {len(skill.files())}")
+
+# To use these skills with the Claude Agent SDK:
+#
+#   from claude_agent_sdk import ClaudeAgentOptions, query
+#
+#   options = ClaudeAgentOptions(
+#       cwd=str(Path(__file__).resolve().parents[1]),
+#       setting_sources=["project"],
+#       allowed_tools=["Skill", "Read", "Grep", "Glob", "Bash"],
+#       max_turns=4,
+#   )
+#
+#   async for message in query(prompt="What skills are available?", options=options):
+#       ...

examples/openai/hosted_inline_skill.py

@@ -1,24 +1,51 @@
-"""Example: Export a skill as an inline zip for OpenAI Agents.
+"""Load a Musher skill as an inline hosted OpenAI shell skill.
 
-Exports a single skill as a base64-encoded zip suitable for hosted inline
-consumption by the OpenAI Agents SDK.
+Requires: pip install openai-agents
 """
 
+import asyncio
+
+from agents import Agent, Runner, ShellTool
+
 import musher
 
-# NOTE: Bundle references below (e.g. "acme/agent-toolkit:2.0.0") are
+# NOTE: Bundle references below (e.g. "acme/data-workflows:2.0.0") are
 # placeholders. Replace with a real bundle ref from your Musher registry.
 
 # Credentials auto-discovered from MUSHER_API_KEY env var, keyring,
 # or credential file. To override: musher.configure(token="your-token")
 
-bundle = musher.pull("acme/agent-toolkit:2.0.0")
-
-# Get a single skill
+bundle = musher.pull("acme/data-workflows:2.0.0")
 skill = bundle.skill("csv-insights")
-
-# PREVIEW: export_openai_inline_skill() is not yet implemented — will raise NotImplementedError.
 inline = skill.export_openai_inline_skill()
-print(f"Inline skill: {inline.name}")
-print(f"  Base64 size: {len(inline.content_base64)} chars")
-print(f"  Registration dict: {inline.to_dict()}")
+
+agent = Agent(
+    name="Hosted CSV Analyst",
+    model="gpt-4.1",
+    instructions="Use the inline skill when it helps.",
+    tools=[
+        ShellTool(
+            environment={
+                "type": "container_auto",
+                "network_policy": {"type": "disabled"},
+                "skills": [inline.to_dict()],
+            }
+        )
+    ],
+)
+
+
+async def main() -> None:
+    result = await Runner.run(
+        agent,
+        (
+            "Use the csv-insights skill. Create /mnt/data/orders.csv with columns "
+            "id,region,amount,status and at least 8 rows. Then report total amount "
+            "by region and count failed orders."
+        ),
+    )
+    print(result.final_output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/openai/local_shell_skill.py

@@ -1,23 +1,90 @@
-"""Example: Export a skill as a local directory for OpenAI Agents.
+"""Load a Musher skill as a local OpenAI shell skill and use it on this repo.
 
-Exports a single skill to disk so it can be loaded as a local shell skill
-by the OpenAI Agents SDK.
+Requires: pip install openai-agents
 """
 
+import asyncio
+from pathlib import Path
+
+from agents import (
+    Agent,
+    Runner,
+    ShellCallOutcome,
+    ShellCommandOutput,
+    ShellCommandRequest,
+    ShellResult,
+    ShellTool,
+)
+
 import musher
 
-# NOTE: Bundle references below (e.g. "acme/agent-toolkit:2.0.0") are
+# NOTE: Bundle references below (e.g. "acme/engineering-workflows:2.0.0") are
 # placeholders. Replace with a real bundle ref from your Musher registry.
 
 # Credentials auto-discovered from MUSHER_API_KEY env var, keyring,
 # or credential file. To override: musher.configure(token="your-token")
 
-bundle = musher.pull("acme/agent-toolkit:2.0.0")
+PROJECT_DIR = Path(__file__).resolve().parents[2]
+
+
+class RepoShell:
+    """Minimal local shell executor for the OpenAI Agents SDK."""
+
+    def __init__(self, cwd: Path) -> None:
+        self.cwd = cwd
+
+    async def __call__(self, request: ShellCommandRequest) -> ShellResult:
+        outputs: list[ShellCommandOutput] = []
+
+        for command in request.data.action.commands:
+            proc = await asyncio.create_subprocess_shell(
+                command,
+                cwd=self.cwd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await proc.communicate()
+
+            outputs.append(
+                ShellCommandOutput(
+                    command=command,
+                    stdout=stdout.decode("utf-8", errors="ignore"),
+                    stderr=stderr.decode("utf-8", errors="ignore"),
+                    outcome=ShellCallOutcome(type="exit", exit_code=proc.returncode),
+                )
+            )
+
+        return ShellResult(
+            output=outputs,
+            max_output_length=request.data.action.max_output_length,
+            provider_data={"working_directory": str(self.cwd)},
+        )
+
+
+bundle = musher.pull("acme/engineering-workflows:2.0.0")
+skill = bundle.skill("repo-maintainer")
+local = skill.export_openai_local_skill(dest=PROJECT_DIR / ".musher" / "openai" / "skills")
+
+agent = Agent(
+    name="Repo Triage Assistant",
+    model="gpt-4.1",
+    instructions="Use the local skill when it helps. Keep the answer concise and actionable.",
+    tools=[
+        ShellTool(
+            executor=RepoShell(PROJECT_DIR),
+            environment={"type": "local", "skills": [local.to_dict()]},
+        )
+    ],
+)
+
+
+async def main() -> None:
+    result = await Runner.run(
+        agent,
+        "Use the repo-maintainer skill to inspect this repository and tell me the first onboarding issue I should fix.",
+    )
+    print(result.final_output)
 
-# Get a single skill
-skill = bundle.skill("csv-insights")
 
-# PREVIEW: export_openai_local_skill() is not yet implemented — will raise NotImplementedError.
-local = skill.export_openai_local_skill()
-print(f"Local skill: {local.name} at {local.path}")
-print(f"  Registration dict: {local.to_dict()}")
+if __name__ == "__main__":
+    asyncio.run(main())

pyproject.toml

@@ -12,6 +12,11 @@ dependencies = [
     "pydantic>=2.12",
 ]
 
+[project.optional-dependencies]
+examples = [
+    "openai-agents>=0.1",
+]
+
 [dependency-groups]
 dev = [
     "ruff>=0.15.2",

src/musher/_bundle.py

@@ -2,13 +2,19 @@
 
 from __future__ import annotations
 
+import json as _json
+import shutil
 from dataclasses import dataclass, field
-from pathlib import PurePosixPath
+from datetime import UTC, datetime
+from pathlib import Path, PurePosixPath
 from typing import TYPE_CHECKING
 
 from pydantic import BaseModel, ConfigDict
 from pydantic.alias_generators import to_camel
 
+if TYPE_CHECKING:
+    from musher._export import ClaudePluginExport
+
 from musher._handles import (
     AgentSpecHandle,
     BundleSelection,
@@ -19,11 +25,6 @@
 )
 from musher._types import AssetType, BundleSourceType, BundleVersionState
 
-if TYPE_CHECKING:
-    from pathlib import Path
-
-    from musher._export import ClaudePluginExport
-
 
 class _SDKSchema(BaseModel):
     """Base schema with camelCase aliasing, matching the platform API wire format."""
@@ -295,8 +296,8 @@ def export_claude_plugin(
         skills: list[str] | None = None,
         dest: Path | None = None,
     ) -> ClaudePluginExport:
-        """Export bundle as a Claude plugin. Raises NotImplementedError (stub)."""
-        raise NotImplementedError
+        """Export bundle as a Claude plugin."""
+        return self.select(skills=skills).export_claude_plugin(plugin_name, dest=dest)
 
     def install_vscode_skills(
         self,
@@ -315,8 +316,32 @@ def install_claude_skills(
         *,
         clean: bool = False,
     ) -> None:
-        """Install skills to a Claude skills directory. Raises NotImplementedError (stub)."""
-        raise NotImplementedError
+        """Install skills to a Claude skills directory."""
+        selection = self.select(skills=skills)
+
+        if clean and dest.is_dir():
+            for child in dest.iterdir():
+                marker = child / ".musher-managed"
+                if child.is_dir() and marker.is_file():
+                    try:
+                        info = _json.loads(marker.read_text(encoding="utf-8"))
+                    except (OSError, _json.JSONDecodeError):
+                        continue
+                    if info.get("bundle_ref") == self.ref:
+                        shutil.rmtree(child)
+
+        dest.mkdir(parents=True, exist_ok=True)
+
+        for skill in selection.skills():
+            skill.export_path(dest=dest)
+            marker_data = {
+                "bundle_ref": self.ref,
+                "bundle_version": self.version,
+                "installed_at": datetime.now(UTC).isoformat(),
+            }
+            (dest / skill.name / ".musher-managed").write_text(
+                _json.dumps(marker_data, indent=2) + "\n", encoding="utf-8"
+            )
 
     def write_lockfile(self, dest: Path | None = None) -> Path:
         """Write a lockfile for the current bundle. Raises NotImplementedError (stub)."""

src/musher/_export.py

@@ -13,6 +13,7 @@
 class ClaudePluginExport:
     """Result of exporting a bundle selection as a Claude plugin."""
 
+    plugin_name: str
     path: Path