Experimental/skills over mcp v2 base

examples/mcp/skills-over-mcp/README.md

@@ -0,0 +1,90 @@
+# Skills-over-MCP demo
+
+This example runs a tiny MCP server that publishes Agent Skills through the
+Skills-over-MCP discovery resource:
+
+```text
+skill://index.json
+```
+
+The server exposes:
+
+- a concrete `pirate` skill at `skill://pirate/SKILL.md`
+- a reference file at `skill://pirate/references/example.md`
+- a template skill namespace at `skill://docs/{product}/SKILL.md`
+
+## Start with the Server enabled
+
+```bash
+fast-agent --stdio "uv run skill_server.py"
+```
+
+## Run the scripted demo
+
+From this directory:
+
+```bash
+uv run example.py
+```
+
+The demo uses the passthrough model to call `read_skill` directly for the
+MCP-served skill and one associated resource.
+
+`example.py` prints human-readable demo output. If a client expects MCP
+JSON-RPC on stdout it will try to parse that text as protocol messages and
+fail.
+
+## Run just the MCP server
+
+If you want to connect another MCP client directly to the Skills-over-MCP
+server, point it at the server script instead:
+
+```bash
+uv run skill_server.py
+```
+
+For fast-agent config, this is already wired in `fast-agent.yaml` as:
+
+```yaml
+mcp:
+  targets:
+    - name: skill_demo
+      target: "uv run skill_server.py"
+```
+
+## Try it interactively
+
+From this directory:
+
+```bash
+uv run fast-agent --env . go
+```
+
+Useful commands:
+
+```text
+/skills
+/skills preview pirate
+/skills templates
+/skills resolve 1 product=alpha
+/skills preview alpha
+/skills disable pirate
+/skills enable pirate
+```
+
+The `pirate` and resolved `alpha` skills are served by the MCP server, not
+loaded from local disk. Their content is returned through `read_skill` wrapped
+as untrusted MCP-provided input.
+
+## Disable Skills-over-MCP for the server
+
+Set `mcp_skills: false` on the server to keep the MCP target connected while
+suppressing `skill://index.json` discovery:
+
+```yaml
+mcp:
+  targets:
+    - name: skill_demo
+      target: "uv run skill_server.py"
+      mcp_skills: false
+```

examples/mcp/skills-over-mcp/example.py

@@ -0,0 +1,40 @@
+"""Manual demo for Skills-over-MCP discovery.
+
+Run from this directory:
+    uv run example.py
+
+For the full interactive flow, run `uv run fast-agent --env . go` and try the slash
+commands listed in README.md.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from fast_agent import FastAgent
+
+fast = FastAgent("Skills-over-MCP demo", config_path="fast-agent.yaml")
+
+
+@fast.agent(
+    instruction=(
+        "You are a passthrough demo agent. Available skills, if any, are "
+        "listed in the system prompt."
+    ),
+    servers=["skill_demo"],
+)
+async def main() -> None:
+    async with fast.run() as agent:
+        print("\n=== read MCP-served skill ===")
+        result = await agent.send('***CALL_TOOL read_skill {"path":"skill://pirate/SKILL.md"}')
+        print(result)
+
+        print("\n=== read MCP-served skill reference ===")
+        ref = await agent.send(
+            '***CALL_TOOL read_skill {"path":"skill://pirate/references/example.md"}'
+        )
+        print(ref)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/mcp/skills-over-mcp/fast-agent.yaml

@@ -0,0 +1,10 @@
+default_model: "passthrough"
+
+logger:
+  level: "error"
+  type: "console"
+
+mcp:
+  targets:
+    - name: skill_demo
+      target: "uv run skill_server.py"

examples/mcp/skills-over-mcp/skill_server.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Tiny Skills-over-MCP demo server.
+
+Run from this directory with:
+    uv run skill_server.py
+"""
+
+from __future__ import annotations
+
+import json
+
+from fastmcp import FastMCP
+from mcp.types import Completion, ResourceTemplateReference
+
+mcp = FastMCP("Skills-over-MCP Demo Server")
+
+DOC_PRODUCTS = ("alpha", "beta")
+TEMPLATE_URI = "skill://docs/{product}/SKILL.md"
+
+INDEX = {
+    "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+    "skills": [
+        {
+            "type": "skill-md",
+            "url": "skill://pirate/SKILL.md",
+        },
+        {
+            "type": "mcp-resource-template",
+            "url": TEMPLATE_URI,
+            "description": "Product-specific documentation skills.",
+        },
+    ],
+}
+
+
+@mcp.resource("skill://index.json", mime_type="application/json")
+def skill_index() -> str:
+    """Skills-over-MCP discovery index."""
+    return json.dumps(INDEX)
+
+
+@mcp.resource("skill://pirate/SKILL.md", mime_type="text/markdown")
+def pirate_skill() -> str:
+    return """---
+name: pirate
+description: Answer in an exaggerated pirate style.
+---
+
+When using this skill, rewrite the answer in pirate dialect. Use nautical
+phrases, but keep the answer useful and concise.
+"""
+
+
+@mcp.resource("skill://pirate/references/example.md", mime_type="text/markdown")
+def pirate_example() -> str:
+    return """# Pirate style example
+
+Plain: The server is ready.
+Pirate: Arrr, the server be ready to sail.
+"""
+
+
+@mcp.resource(TEMPLATE_URI, mime_type="text/markdown")
+def product_docs_skill(product: str) -> str:
+    if product == "alpha":
+        guidance = "Prefer Alpha examples about onboarding, setup, and first-run UX."
+    elif product == "beta":
+        guidance = "Prefer Beta examples about reporting, exports, and audit trails."
+    else:
+        guidance = f"Use general documentation examples for {product}."
+
+    return f"""---
+name: {product}
+description: Product documentation guidance for {product}.
+---
+
+When using this skill, answer as a product documentation specialist for
+`{product}`. {guidance}
+"""
+
+
+@mcp._mcp_server.completion()
+async def complete_resource_template_argument(ref, argument, context):
+    """Suggest values for skill://docs/{product}/SKILL.md."""
+    del context
+
+    if not isinstance(ref, ResourceTemplateReference):
+        return Completion(values=[])
+    if ref.uri != TEMPLATE_URI or argument.name != "product":
+        return Completion(values=[])
+
+    prefix = argument.value or ""
+    values = [product for product in DOC_PRODUCTS if product.startswith(prefix)]
+    return Completion(values=values, total=len(DOC_PRODUCTS), hasMore=False)
+
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")