Upload 7 files

HOWTO.md

@@ -0,0 +1,448 @@
+# ⚒️ FORGE — Complete How-To Guide
+
+## Table of Contents
+1. [What is FORGE?](#what-is-forge)
+2. [vs ClawHub](#vs-clawhub)
+3. [Deploy to HuggingFace](#deploy)
+4. [Skill Formats](#skill-formats)
+5. [CRUD — Create, Read, Update, Delete](#crud)
+6. [MCP Server — Claude native integration](#mcp)
+7. [Bins & Node Tools](#bins-and-node-tools)
+8. [Claude Skills (Anthropic API)](#claude-skills)
+9. [Agent Quick Start](#agent-quick-start)
+10. [REST API Reference](#rest-api)
+
+---
+
+## What is FORGE?
+
+FORGE is a **skill artifactory for AI agents** — like npm, pip, or JFrog Artifactory but for executable agent capabilities.
+
+Every skill is a self-contained, versioned unit that any agent can:
+- **Discover** via REST API or MCP protocol
+- **Download** as code (Python / Node.js / shell) or as a SKILL.md description
+- **Hot-load** at runtime without retraining or redeployment
+- **Execute** through a standard `execute()` interface
+
+---
+
+## vs ClawHub
+
+| Feature | ClawHub | FORGE |
+|---------|---------|-------|
+| Primary format | SKILL.md (markdown) | JSON + embedded code |
+| Also supports | — | SKILL.md (ClawHub compatible) ✅ |
+| Code execution | Instructions only | Live executable Python ✅ |
+| MCP Server | ❌ | ✅ |
+| Bins / Node tools | Via Nix | Via `runtime` metadata |
+| Claude skills | ❌ | ✅ (Anthropic API) |
+| HF Space deploy | ❌ | ✅ one-click |
+| Vector search | ✅ (OpenAI embeddings) | tag + text search |
+| 3000+ community skills | ✅ | growing |
+
+**Key difference:** ClawHub skills are *instructions* (markdown that goes into an LLM prompt). FORGE skills are *executable code* that agents run directly. You can publish both.
+
+---
+
+## Deploy
+
+### HuggingFace Space (recommended)
+
+```bash
+# 1. Create Space at huggingface.co → SDK: Gradio
+# 2. Clone your space
+git clone https://huggingface.co/spaces/YOUR_NAME/agent-forge
+cd agent-forge
+
+# 3. Copy FORGE files into it
+cp -r forge/* .
+
+# 4. Push
+git add . && git commit -m "Deploy FORGE" && git push
+```
+
+The `README.md` frontmatter configures the Space:
+```yaml
+---
+title: FORGE Agent Skill Artifactory
+emoji: ⚒️
+colorFrom: orange
+colorTo: red
+sdk: gradio
+sdk_version: 4.44.0
+app_file: app.py
+pinned: true
+---
+```
+
+### Local dev
+
+```bash
+pip install -r requirements.txt
+python app.py
+# → http://localhost:7860
+```
+
+---
+
+## Skill Formats
+
+FORGE supports **three skill formats**:
+
+### Format 1: JSON (executable Python)
+Best for: skills that agents hot-load and execute directly.
+
+```json
+{
+  "id": "my_skill",
+  "name": "My Skill",
+  "version": "1.0.0",
+  "description": "What this skill does",
+  "author": "yourname",
+  "tags": ["utility"],
+  "dependencies": ["requests"],
+  "runtime": "python",
+  "schema": {
+    "input":  { "text": "str" },
+    "output": { "result": "str" }
+  },
+  "code": "def execute(text: str) -> dict:\n    return {'result': text.upper()}"
+}
+```
+
+### Format 2: SKILL.md (ClawHub compatible)
+Best for: LLM-readable instructions that go into agent prompts.
+
+```markdown
+---
+name: my-skill
+version: 1.0.0
+description: Does something useful
+author: yourname
+tags: [utility, text]
+runtime: instructions
+---
+
+# My Skill
+
+## Purpose
+Explain what this skill teaches an agent to do.
+
+## Usage
+When the user asks to process text, do the following:
+1. Step one
+2. Step two
+
+## Examples
+Input: "hello world"
+Output: "HELLO WORLD"
+```
+
+### Format 3: Node.js / Shell tool
+Best for: wrapping CLI tools, Node scripts, or system binaries.
+
+```json
+{
+  "id": "node_parser",
+  "name": "JSON Parser",
+  "version": "1.0.0",
+  "runtime": "node",
+  "dependencies_node": ["lodash"],
+  "bins": ["jq"],
+  "code": "const _ = require('lodash');\nfunction execute({data}) {\n  return { keys: _.keys(JSON.parse(data)) };\n}\nmodule.exports = { execute };"
+}
+```
+
+---
+
+## CRUD
+
+### CREATE — Publish a new skill
+
+**Via UI:** Go to the "📦 Publish" tab → paste your skill JSON → click Publish.
+
+**Via API:**
+```bash
+curl -X POST https://YOUR_SPACE.hf.space/api/v1/skills \
+  -H "Content-Type: application/json" \
+  -d @my_skill.json
+```
+
+**Via Python agent:**
+```python
+forge = bootstrap_forge()
+result = forge.publish({
+    "id": "my_skill",
+    "name": "My Skill",
+    "version": "1.0.0",
+    "description": "...",
+    "author": "me",
+    "tags": ["utility"],
+    "code": "def execute(**kwargs): return {'ok': True}"
+})
+```
+
+---
+
+### READ — Discover and download skills
+
+**Browse UI:** Go to "🔍 Browse" tab — search by keyword or filter by tag.
+
+**Read one skill (metadata only):**
+```bash
+GET /api/v1/skills/calculator
+```
+
+**Read skill code (for hot-loading):**
+```bash
+GET /api/v1/skills/calculator/code
+```
+
+**Download as .py file:**
+```bash
+GET /api/v1/skills/calculator/download
+```
+
+**Full manifest (all skills + code for offline cache):**
+```bash
+GET /api/v1/manifest
+```
+
+**Search:**
+```bash
+GET /api/v1/search?q=math
+GET /api/v1/skills?tag=web
+```
+
+---
+
+### UPDATE — Publish a new version
+
+FORGE uses **semver versioning**. To update a skill, publish it again with a bumped version:
+
+```json
+{
+  "id": "calculator",
+  "version": "1.1.0",   ← bump this
+  ...
+}
+```
+
+Previous versions are kept on disk as `calculator.v1.0.0.json`.
+
+**Via UI:** Skill Detail tab → "Edit" → modify → save as new version.
+
+---
+
+### DELETE — Remove a skill
+
+**Via UI:** Skill Detail tab → "🗑 Delete" button (with confirmation).
+
+**Via API:**
+```bash
+DELETE /api/v1/skills/my_skill
+```
+
+---
+
+## MCP
+
+FORGE exposes an **MCP (Model Context Protocol) server** so Claude Desktop, Claude API, and any MCP client can discover and use skills natively.
+
+### Connect Claude to FORGE
+
+Add to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "forge": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://YOUR_SPACE.hf.space/mcp/sse"]
+    }
+  }
+}
+```
+
+Or via the API with SSE:
+```python
+import anthropic
+
+client = anthropic.Anthropic()
+response = client.beta.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=1024,
+    tools=[],
+    mcp_servers=[{
+        "type": "url",
+        "url": "https://YOUR_SPACE.hf.space/mcp/sse",
+        "name": "forge"
+    }],
+    messages=[{"role": "user", "content": "List all math skills in FORGE"}]
+)
+```
+
+### MCP Tools exposed by FORGE
+
+| Tool | Description |
+|------|-------------|
+| `forge_list_skills` | List all skills, optionally filtered |
+| `forge_search` | Semantic search across skills |
+| `forge_get_skill` | Get full skill including code |
+| `forge_get_code` | Get executable code for a skill |
+| `forge_publish_skill` | Publish a new skill |
+| `forge_get_stats` | Registry statistics |
+
+---
+
+## Bins and Node Tools
+
+Skills can declare required system binaries and Node packages:
+
+```json
+{
+  "id": "pdf_extractor",
+  "runtime": "python",
+  "bins": ["pdftotext", "gs"],
+  "dependencies": ["pypdf2"],
+  "install_notes": "apt-get install poppler-utils ghostscript",
+  "code": "..."
+}
+```
+
+```json
+{
+  "id": "image_optimizer",
+  "runtime": "node",
+  "bins": ["sharp", "imagemagick"],
+  "dependencies_node": ["sharp", "glob"],
+  "code": "const sharp = require('sharp'); ..."
+}
+```
+
+Agents check `skill.bins` before executing and can skip skills whose binaries aren't available on the current host.
+
+### Shell/Bin skill example
+
+```json
+{
+  "id": "git_status",
+  "runtime": "shell",
+  "bins": ["git"],
+  "code": "#!/bin/bash\ngit -C \"$1\" status --porcelain"
+}
+```
+
+---
+
+## Claude Skills
+
+Skills that call the **Anthropic API** — these give your agent Claude-powered capabilities it can invoke as tools.
+
+### Example: Claude Skill structure
+
+```json
+{
+  "id": "claude_summarizer",
+  "runtime": "python",
+  "dependencies": ["anthropic"],
+  "env_required": ["ANTHROPIC_API_KEY"],
+  "code": "import anthropic\n\ndef execute(text: str, style: str = 'bullet') -> dict:\n    client = anthropic.Anthropic()\n    msg = client.messages.create(\n        model='claude-haiku-4-5-20251001',\n        max_tokens=512,\n        messages=[{'role': 'user', 'content': f'Summarize as {style} points:\\n{text}'}]\n    )\n    return {'summary': msg.content[0].text}\n"
+}
+```
+
+### How agents use Claude skills
+
+```python
+forge = bootstrap_forge()
+summarizer = forge.load("claude_summarizer")
+
+# Agents set ANTHROPIC_API_KEY in their environment
+result = summarizer.execute(
+    text="Long article text...",
+    style="executive"
+)
+# → {"summary": "• Key point 1\n• Key point 2..."}
+```
+
+### Available Claude skills in FORGE
+
+| Skill ID | What it does |
+|----------|-------------|
+| `claude_chat` | Single-turn Q&A with Claude |
+| `claude_summarizer` | Summarize text in various styles |
+| `claude_extractor` | Extract structured data from text |
+| `claude_judge` | Evaluate/score outputs (LLM-as-judge) |
+| `claude_coder` | Generate code from a spec |
+
+---
+
+## Agent Quick Start
+
+```python
+import requests, types
+
+# ── Bootstrap (one HTTP call) ──────────────────────────
+def bootstrap_forge(url="https://chris4k-agent-forge.hf.space"):
+    r = requests.get(f"{url}/api/v1/skills/forge_client/code")
+    m = types.ModuleType("forge_client")
+    exec(r.json()["code"], m.__dict__)
+    return m.ForgeClient(url)
+
+forge = bootstrap_forge()
+
+# ── Discover ───────────────────────────────────────────
+all_skills  = forge.list()                        # all skills
+math_skills = forge.list(tag="math")              # by tag
+results     = forge.search("web scraping")        # full-text search
+
+# ── Load & Execute ─────────────────────────────────────
+calc    = forge.load("calculator")
+search  = forge.load("web_search")
+memory  = forge.load("memory_store")
+fetcher = forge.load("http_fetch")
+claude  = forge.load("claude_chat")               # Claude skill
+
+# Run them
+print(calc.execute(expression="2**32 / 1024"))
+print(search.execute(query="AI news today", max_results=3))
+memory.execute(action="set", key="goal", value="research AI", ttl=3600)
+page  = fetcher.execute(url="https://example.com", max_chars=2000)
+reply = claude.execute(prompt="What is MCP?")
+
+# ── Publish your own ───────────────────────────────────
+forge.publish({
+    "id": "my_skill",
+    "name": "My Skill",
+    "version": "1.0.0",
+    "description": "Does something useful",
+    "author": "yourname",
+    "tags": ["utility"],
+    "code": "def execute(**kwargs): return {'ok': True, 'data': kwargs}"
+})
+```
+
+---
+
+## REST API Reference
+
+Base URL: `https://YOUR_SPACE.hf.space`
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/v1/manifest` | Full manifest (all skills + code) |
+| `GET` | `/api/v1/skills` | List skills. Params: `?tag=` `?q=` |
+| `GET` | `/api/v1/skills/{id}` | Get skill metadata + code |
+| `GET` | `/api/v1/skills/{id}/code` | Minimal code payload for hot-loading |
+| `GET` | `/api/v1/skills/{id}/download` | Download as `.py` file |
+| `POST` | `/api/v1/skills` | Publish new skill (JSON body) |
+| `PUT` | `/api/v1/skills/{id}` | Update skill (new version) |
+| `DELETE` | `/api/v1/skills/{id}` | Delete skill |
+| `GET` | `/api/v1/search?q=` | Full-text search |
+| `GET` | `/api/v1/tags` | All tags |
+| `GET` | `/api/v1/stats` | Registry statistics |
+| `GET` | `/mcp/sse` | MCP Server-Sent Events endpoint |
+| `POST` | `/mcp` | MCP JSON-RPC endpoint |
+
+---
+
+*Built by Chris4K · ki-fusion-labs.de · MIT License*

app.py

@@ -0,0 +1,333 @@
+"""
+⚒️ FORGE — Federated Open Registry for Generative Executables
+v2.0 — CRUD UI · MCP Server · SKILL.md support · Claude skills
+"""
+import json
+import time
+from pathlib import Path
+
+import gradio as gr
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse, Response
+
+import skill_registry as registry
+from mcp_server import register_mcp_routes
+
+api = FastAPI(title="FORGE API", version="2.0.0")
+register_mcp_routes(api)
+
+def jresp(data, status=200):
+    return JSONResponse(content=data, status_code=status)
+
+@api.get("/api/v1/manifest")
+async def api_manifest():
+    return jresp(registry.get_manifest())
+
+@api.get("/api/v1/skills")
+async def api_list(tag: str | None = None, q: str | None = None):
+    skills = registry.list_skills(tag=tag, query=q)
+    return jresp({"skills": skills, "count": len(skills)})
+
+@api.get("/api/v1/skills/{skill_id}")
+async def api_get(skill_id: str):
+    s = registry.get_skill(skill_id)
+    if not s: raise HTTPException(404, f"'{skill_id}' not found")
+    return jresp(s)
+
+@api.get("/api/v1/skills/{skill_id}/code")
+async def api_code(skill_id: str):
+    d = registry.get_skill_code(skill_id)
+    if not d: raise HTTPException(404)
+    return jresp(d)
+
+@api.get("/api/v1/skills/{skill_id}/download")
+async def api_download(skill_id: str):
+    d = registry.get_skill_code(skill_id)
+    if not d: raise HTTPException(404)
+    code = f'"""\nFORGE Skill: {skill_id} v{d["version"]}\nhttps://chris4k-agent-forge.hf.space\n"""\n\n{d["code"]}\n'
+    return Response(code, media_type="text/x-python",
+                    headers={"Content-Disposition": f'attachment; filename="{skill_id}.py"'})
+
+@api.post("/api/v1/skills")
+async def api_publish(request: Request):
+    try: skill = await request.json()
+    except Exception: raise HTTPException(400, "Invalid JSON")
+    ok, msg = registry.publish_skill(skill)
+    return jresp({"ok": ok, "message": msg}, 201 if ok else 400)
+
+@api.put("/api/v1/skills/{skill_id}")
+async def api_update(skill_id: str, request: Request):
+    try: updates = await request.json()
+    except Exception: raise HTTPException(400, "Invalid JSON")
+    ok, msg = registry.update_skill(skill_id, updates)
+    return jresp({"ok": ok, "message": msg}, 200 if ok else 404)
+
+@api.delete("/api/v1/skills/{skill_id}")
+async def api_delete(skill_id: str):
+    ok, msg = registry.delete_skill(skill_id)
+    return jresp({"ok": ok, "message": msg}, 200 if ok else 404)
+
+@api.get("/api/v1/search")
+async def api_search(q: str):
+    skills = registry.list_skills(query=q)
+    return jresp({"query": q, "skills": skills, "count": len(skills)})
+
+@api.get("/api/v1/tags")
+async def api_tags():
+    return jresp({"tags": registry.get_all_tags()})
+
+@api.get("/api/v1/stats")
+async def api_stats():
+    return jresp(registry.get_stats())
+
+# ─── CSS ──────────────────────────────────────────────────────────
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&family=Syne:wght@400;600;800&display=swap');
+:root{--fg:#0a0a0f;--surf:#111118;--bord:#1e1e2e;--acc:#ff6b00;--acc2:#ff9500;--txt:#e8e8f0;--mute:#6b6b8a;--grn:#00ff88;--pur:#8b5cf6;--red:#ff4444;}
+body,.gradio-container{background:var(--fg)!important;font-family:'Syne',sans-serif!important;color:var(--txt)!important;}
+.forge-header{text-align:center;padding:2.5rem 1rem 1rem;border-bottom:1px solid var(--bord);margin-bottom:1.5rem;background:linear-gradient(180deg,#0f0f1a 0%,var(--fg) 100%);}
+.forge-logo{font-family:'Space Mono',monospace;font-size:3.2rem;font-weight:700;background:linear-gradient(135deg,var(--acc),var(--acc2));-webkit-background-clip:text;-webkit-text-fill-color:transparent;background-clip:text;letter-spacing:-2px;line-height:1;}
+.forge-sub{font-family:'Space Mono',monospace;font-size:.65rem;color:var(--mute);letter-spacing:.35em;text-transform:uppercase;margin-top:.4rem;}
+.stat-bar{display:flex;justify-content:center;gap:3rem;padding:.8rem;margin:1rem 0 1.5rem;border:1px solid var(--bord);border-radius:8px;background:var(--surf);}
+.stat-num{font-family:'Space Mono',monospace;font-size:1.8rem;color:var(--acc);font-weight:700;}
+.stat-lbl{font-size:.65rem;color:var(--mute);text-transform:uppercase;letter-spacing:.15em;}
+.skill-card{background:var(--surf);border:1px solid var(--bord);border-radius:8px;padding:1.2rem;margin-bottom:.6rem;transition:border-color .2s,transform .1s;}
+.skill-card:hover{border-color:var(--acc);transform:translateX(3px);}
+.skill-name{font-family:'Space Mono',monospace;font-size:.95rem;font-weight:700;color:var(--acc);}
+.skill-desc{font-size:.83rem;color:var(--mute);line-height:1.5;margin-top:.3rem;}
+.tag-pill{display:inline-block;background:#1a1a30;border:1px solid #2a2a50;color:var(--pur);font-family:'Space Mono',monospace;font-size:.6rem;padding:2px 8px;border-radius:20px;margin:3px 2px 0;}
+.api-row{background:var(--surf);border-left:3px solid var(--acc);padding:.6rem 1rem;margin:.4rem 0;border-radius:0 6px 6px 0;font-family:'Space Mono',monospace;font-size:.75rem;}
+.m-get{color:var(--grn);}.m-post{color:var(--acc2);}.m-put{color:#60a5fa;}.m-del{color:var(--red);}
+.mcp-badge{background:#1a0a30;border:1px solid #5b21b650;border-radius:6px;padding:.75rem 1rem;margin:.5rem 0;font-family:'Space Mono',monospace;font-size:.75rem;color:#a78bfa;}
+.gr-button{background:var(--acc)!important;color:#000!important;font-family:'Space Mono',monospace!important;font-weight:700!important;border:none!important;}
+.gr-button:hover{background:var(--acc2)!important;}
+textarea,input{background:var(--surf)!important;border-color:var(--bord)!important;color:var(--txt)!important;}
+label span{color:var(--mute)!important;font-family:'Space Mono',monospace!important;font-size:.72rem!important;letter-spacing:.1em!important;}
+.tab-nav button{background:var(--surf)!important;color:var(--mute)!important;border:1px solid var(--bord)!important;font-family:'Space Mono',monospace!important;font-size:.75rem!important;}
+.tab-nav button.selected{color:var(--acc)!important;border-bottom-color:var(--acc)!important;}
+"""
+
+PUBLISH_TEMPLATE = """{
+  "id": "my_skill",
+  "name": "My Skill",
+  "version": "1.0.0",
+  "description": "What this skill does for an agent.",
+  "author": "Chris4K",
+  "tags": ["utility"],
+  "runtime": "python",
+  "dependencies": [],
+  "env_required": [],
+  "bins": [],
+  "schema": {
+    "input":  { "text": "str" },
+    "output": { "result": "str" }
+  },
+  "code": "def execute(text: str) -> dict:\\n    return {'result': text.upper()}\\n"
+}"""
+
+SKILL_MD_TEMPLATE = """---
+name: my-instructions-skill
+version: 1.0.0
+description: Teach an agent how to do something step-by-step.
+author: Chris4K
+tags: [instructions, utility]
+runtime: instructions
+---
+
+# My Instructions Skill
+
+## Purpose
+Describe what capability this adds to an agent.
+
+## When to use
+Use this skill when the user asks you to...
+
+## Steps
+1. First, do this
+2. Then do that
+3. Finally return the result
+
+## Examples
+Input: "some example"
+Output: "expected output"
+"""
+
+def fmt_card(s):
+    tags = "".join(f'<span class="tag-pill">{t}</span>' for t in s.get("tags",[]))
+    rt = s.get("runtime","python")
+    return f"""<div class="skill-card">
+<div class="skill-name">⚙ {s['name']} <span style="font-size:.65rem;color:#555570;margin-left:6px">[{rt}]</span>
+  <span style="float:right;font-size:.65rem;color:#4a4a6a">↓{s.get('downloads',0)} · v{s['version']}</span></div>
+<div style="font-family:'Space Mono',monospace;font-size:.62rem;color:#4a4a6a;margin:2px 0 6px">by {s['author']} · <span style="color:#ff6b0060">{s['id']}</span></div>
+<div class="skill-desc">{s['description'][:150]}{'…' if len(s['description'])>150 else ''}</div>
+<div style="margin-top:6px">{tags}</div></div>"""
+
+def render_list(skills):
+    if not skills: return '<div style="color:#4a4a6a;text-align:center;padding:2rem;font-family:Space Mono">No skills found.</div>'
+    return "".join(fmt_card(s) for s in skills)
+
+def render_stats():
+    st = registry.get_stats()
+    return f"""<div class="stat-bar">
+<div><div class="stat-num">{st['total_skills']}</div><div class="stat-lbl">Skills</div></div>
+<div><div class="stat-num">{st['total_downloads']}</div><div class="stat-lbl">Downloads</div></div>
+<div><div class="stat-num">{st['total_tags']}</div><div class="stat-lbl">Tags</div></div>
+<div><div class="stat-num">✓</div><div class="stat-lbl">MCP Live</div></div></div>"""
+
+def do_browse(q, tag):
+    return render_list(registry.list_skills(tag=None if tag=="all" else tag, query=q.strip() or None))
+
+def load_detail(skill_id):
+    if not skill_id.strip(): return ("Enter a skill ID.", "", "", "", "")
+    s = registry.get_skill(skill_id.strip())
+    if not s: return (f"Skill '{skill_id}' not found.", "", "", "", "")
+    tags_html = " ".join(f'<span class="tag-pill">{t}</span>' for t in s.get("tags",[]))
+    meta = f"""<div class="skill-card">
+<div class="skill-name">⚙ {s['name']} <span style="font-size:.65rem;color:#555570">[{s.get('runtime','python')}]</span></div>
+<div style="font-family:'Space Mono',monospace;font-size:.68rem;color:#6b6b8a">v{s['version']} · by {s['author']} · ↓{s.get('downloads',0)}</div>
+<div style="margin:.6rem 0;line-height:1.6">{s['description']}</div><div>{tags_html}</div>
+{"<div style='margin-top:.4rem;font-size:.65rem;color:#ff4444;font-family:Space Mono,monospace'>⚠ env: "+', '.join(s['env_required'])+"</div>" if s.get('env_required') else ""}
+{"<div style='margin-top:.4rem;font-size:.65rem;color:#60a5fa;font-family:Space Mono,monospace'>🔧 bins: "+', '.join(s.get('bins',[]))+"</div>" if s.get('bins') else ""}
+<div style="margin-top:.75rem;border-top:1px solid #1e1e2e;padding-top:.5rem">
+<strong style="color:#8b5cf6;font-size:.65rem;font-family:Space Mono,monospace">SCHEMA</strong>
+<pre style="font-size:.65rem;color:#8080a0;margin-top:.3rem">{json.dumps(s.get('schema',{}),indent=2)}</pre></div></div>"""
+    code = s.get("code","")
+    instructions = s.get("instructions","(no markdown instructions)")
+    usage = f"""# ⚒️ Quick Start: {s['id']}
+import requests, types
+def bootstrap_forge(url="https://chris4k-agent-forge.hf.space"):
+    r = requests.get(f"{{url}}/api/v1/skills/forge_client/code")
+    m = types.ModuleType("forge_client")
+    exec(r.json()["code"], m.__dict__)
+    return m.ForgeClient(url)
+
+forge = bootstrap_forge()
+{s['id']} = forge.load("{s['id']}")
+result = {s['id']}.execute()  # see schema above
+print(result)
+"""
+    edit_json = json.dumps({k:v for k,v in s.items() if k not in ("created_at","updated_at","downloads")}, indent=2)
+    return meta, code, instructions, usage, edit_json
+
+def do_update(skill_id, edit_json):
+    if not skill_id.strip(): return "⚠ No skill loaded"
+    try: updates = json.loads(edit_json)
+    except json.JSONDecodeError as e: return f"❌ JSON error: {e}"
+    ok, msg = registry.update_skill(skill_id.strip(), updates)
+    return ("✅ " if ok else "❌ ") + msg
+
+def do_delete(skill_id):
+    if not skill_id.strip(): return "⚠ No skill loaded"
+    ok, msg = registry.delete_skill(skill_id.strip())
+    return ("✅ " if ok else "❌ ") + msg
+
+def publish_json(skill_json):
+    try: skill = json.loads(skill_json)
+    except json.JSONDecodeError as e: return f"❌ Invalid JSON: {e}"
+    ok, msg = registry.publish_skill(skill)
+    return ("✅ " if ok else "❌ ") + msg
+
+def publish_md(skill_md):
+    skill, err = registry.parse_skill_md(skill_md)
+    if err: return f"❌ {err}"
+    ok, msg = registry.publish_skill(skill)
+    return ("✅ Published as '"+skill["id"]+"' — " if ok else "❌ ") + msg
+
+def build_app():
+    with gr.Blocks(css=CSS, title="⚒️ FORGE") as demo:
+        gr.HTML("""<div class="forge-header">
+          <div class="forge-logo">⚒ FORGE</div>
+          <div class="forge-sub">Federated Open Registry for Generative Executables</div>
+          <div style="color:#4a4a6a;font-size:.78rem;margin-top:.6rem">Python · Node · SKILL.md · MCP · Claude Skills</div>
+        </div>""")
+        stats_html = gr.HTML(render_stats())
+
+        with gr.Tabs():
+            with gr.Tab("🔍 Browse"):
+                with gr.Row():
+                    search_in = gr.Textbox(placeholder="search…", label="Search", scale=3)
+                    tag_dd = gr.Dropdown(choices=["all"]+registry.get_all_tags(), value="all", label="Tag", scale=1)
+                srch_btn = gr.Button("Search", variant="primary", size="sm")
+                skills_out = gr.HTML(render_list(registry.list_skills()))
+                srch_btn.click(do_browse, [search_in, tag_dd], skills_out)
+                search_in.submit(do_browse, [search_in, tag_dd], skills_out)
+                tag_dd.change(do_browse, [search_in, tag_dd], skills_out)
+
+            with gr.Tab("⚙ Skill CRUD"):
+                skill_id_in = gr.Textbox(placeholder="e.g. calculator, claude_chat…", label="Skill ID")
+                with gr.Row():
+                    load_btn   = gr.Button("Load", variant="primary", size="sm")
+                    update_btn = gr.Button("💾 Save Changes", size="sm")
+                    delete_btn = gr.Button("🗑 Delete", size="sm")
+                crud_msg = gr.Textbox(label="Status", interactive=False, lines=1)
+                detail_meta = gr.HTML()
+                with gr.Tabs():
+                    with gr.Tab("📄 Code"):
+                        detail_code = gr.Code(language="python", label="Skill code")
+                    with gr.Tab("📝 SKILL.md"):
+                        detail_md = gr.Markdown()
+                    with gr.Tab("🤖 Agent Usage"):
+                        detail_use = gr.Code(language="python", label="Quick start")
+                    with gr.Tab("✏️ Edit JSON"):
+                        edit_json_in = gr.Code(language="json", label="Edit → Save Changes")
+                load_btn.click(load_detail, skill_id_in, [detail_meta, detail_code, detail_md, detail_use, edit_json_in])
+                skill_id_in.submit(load_detail, skill_id_in, [detail_meta, detail_code, detail_md, detail_use, edit_json_in])
+                update_btn.click(do_update, [skill_id_in, edit_json_in], crud_msg)
+                delete_btn.click(do_delete, skill_id_in, crud_msg)
+
+            with gr.Tab("📦 Publish"):
+                with gr.Tabs():
+                    with gr.Tab("JSON (executable)"):
+                        pub_json_in = gr.Code(value=PUBLISH_TEMPLATE, language="json", label="Skill JSON", lines=22)
+                        gr.Button("⚒ Publish JSON Skill", variant="primary").click(publish_json, pub_json_in, gr.Textbox(label="Result", interactive=False))
+                    with gr.Tab("SKILL.md (ClawHub compat)"):
+                        pub_md_in = gr.Code(value=SKILL_MD_TEMPLATE, language="markdown", label="SKILL.md", lines=22)
+                        gr.Button("⚒ Publish SKILL.md", variant="primary").click(publish_md, pub_md_in, gr.Textbox(label="Result", interactive=False))
+
+            with gr.Tab("🔌 MCP"):
+                gr.HTML("""<div style="padding:1rem">
+                <h2 style="color:#ff6b00;font-family:'Space Mono',monospace">⚒️ MCP Server</h2>
+                <p style="color:#6b6b8a">Connect Claude Desktop, Claude API, or any MCP client.</p>
+                <div class="mcp-badge"><strong>SSE (Claude Desktop)</strong><br>
+                <code>https://chris4k-agent-forge.hf.space/mcp/sse</code></div>
+                <div class="mcp-badge"><strong>JSON-RPC (API)</strong><br>
+                <code>https://chris4k-agent-forge.hf.space/mcp</code></div>
+                <h3 style="color:#8b5cf6;margin:1rem 0 .5rem;font-family:'Space Mono',monospace">Claude Desktop Config</h3>
+                <pre style="background:#0d0d1a;border:1px solid #1e1e2e;border-radius:6px;padding:1rem;font-size:.72rem;color:#00ff88">{"mcpServers":{"forge":{"command":"npx","args":["-y","mcp-remote","https://chris4k-agent-forge.hf.space/mcp/sse"]}}}</pre>
+                <h3 style="color:#8b5cf6;margin:1rem 0 .5rem;font-family:'Space Mono',monospace">MCP Tools</h3>
+                <div class="api-row">forge_list_skills · forge_get_skill · forge_get_code · forge_search · forge_publish_skill · forge_get_stats</div>
+                </div>""")
+
+            with gr.Tab("📡 API"):
+                gr.HTML("""<div style="font-family:'Space Mono',monospace;padding:1rem">
+                <h2 style="color:#ff6b00">REST API v2</h2>
+                <div class="api-row"><span class="m-get">GET</span> /api/v1/skills — list</div>
+                <div class="api-row"><span class="m-get">GET</span> /api/v1/skills/{id}/code — hot-load code</div>
+                <div class="api-row"><span class="m-get">GET</span> /api/v1/skills/{id}/download — .py file</div>
+                <div class="api-row"><span class="m-post">POST</span> /api/v1/skills — publish</div>
+                <div class="api-row"><span class="m-put">PUT</span> /api/v1/skills/{id} — update</div>
+                <div class="api-row"><span class="m-del">DEL</span> /api/v1/skills/{id} — delete</div>
+                <div class="api-row"><span class="m-get">GET</span> /api/v1/search?q= — search</div>
+                <div class="api-row"><span class="m-get">GET</span> /api/v1/manifest — full manifest</div>
+                <div class="api-row"><span class="m-get">GET</span> /mcp/sse — MCP SSE stream</div>
+                <div class="api-row"><span class="m-post">POST</span> /mcp — MCP JSON-RPC</div>
+                <pre style="background:#0d0d1a;border:1px solid #1e1e2e;border-radius:6px;padding:1rem;margin-top:1rem;font-size:.72rem;color:#00ff88">forge = bootstrap_forge()
+calc = forge.load("calculator")
+print(calc.execute(expression="2**32"))</pre></div>""")
+
+            with gr.Tab("📖 How-To"):
+                howto_path = Path(__file__).parent / "HOWTO.md"
+                howto_text = howto_path.read_text(encoding="utf-8") if howto_path.exists() else "HOWTO.md not found"
+                gr.Markdown(howto_text)
+
+        gr.HTML("""<div style="text-align:center;padding:1.5rem;border-top:1px solid #1e1e2e;margin-top:2rem;
+             font-family:'Space Mono',monospace;font-size:.65rem;color:#3a3a5a">
+          ⚒️ FORGE v2.0 · ki-fusion-labs.de · <a href="https://huggingface.co/Chris4K" style="color:#ff6b00">Chris4K</a> · MIT
+        </div>""")
+    return demo
+
+demo = build_app()
+app  = gr.mount_gradio_app(api, demo, path="/")
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860)

claude_chat.json

@@ -0,0 +1,28 @@
+{
+  "id": "claude_chat",
+  "name": "Claude Chat",
+  "version": "1.0.0",
+  "description": "Single-turn Q&A powered by Claude (Anthropic API). Agents can delegate reasoning, analysis, code generation, or any LLM task to Claude as a sub-skill. Requires ANTHROPIC_API_KEY env var.",
+  "author": "Chris4K",
+  "tags": ["claude", "anthropic", "llm", "reasoning", "ai"],
+  "runtime": "python",
+  "dependencies": ["anthropic"],
+  "env_required": ["ANTHROPIC_API_KEY"],
+  "schema": {
+    "input": {
+      "prompt": "str — the question or instruction for Claude",
+      "system": "str — optional system prompt (default: helpful assistant)",
+      "model": "str — model ID (default: claude-haiku-4-5-20251001)",
+      "max_tokens": "int — max response tokens (default: 1024)"
+    },
+    "output": {
+      "response": "str — Claude's response text",
+      "model": "str — model used",
+      "input_tokens": "int",
+      "output_tokens": "int"
+    }
+  },
+  "code": "import os\nfrom typing import Optional\n\n\ndef execute(\n    prompt: str,\n    system: str = \"You are a helpful AI assistant embedded in an agent skill.\",\n    model: str = \"claude-haiku-4-5-20251001\",\n    max_tokens: int = 1024,\n    api_key: Optional[str] = None,\n) -> dict:\n    \"\"\"\n    Send a single-turn message to Claude and return the response.\n    Used by agents to delegate LLM reasoning tasks.\n    \"\"\"\n    try:\n        import anthropic\n    except ImportError:\n        return {\"error\": \"anthropic package not installed. Run: pip install anthropic\"}\n\n    key = api_key or os.environ.get(\"ANTHROPIC_API_KEY\")\n    if not key:\n        return {\"error\": \"ANTHROPIC_API_KEY not set. Pass api_key= or set the env var.\"}\n\n    if not prompt or not prompt.strip():\n        return {\"error\": \"prompt cannot be empty\"}\n\n    client = anthropic.Anthropic(api_key=key)\n\n    try:\n        msg = client.messages.create(\n            model=model,\n            max_tokens=max_tokens,\n            system=system,\n            messages=[{\"role\": \"user\", \"content\": prompt}],\n        )\n        response_text = msg.content[0].text if msg.content else \"\"\n        return {\n            \"response\": response_text,\n            \"model\": model,\n            \"input_tokens\": msg.usage.input_tokens,\n            \"output_tokens\": msg.usage.output_tokens,\n            \"stop_reason\": msg.stop_reason,\n        }\n    except anthropic.AuthenticationError:\n        return {\"error\": \"Invalid ANTHROPIC_API_KEY\"}\n    except anthropic.RateLimitError:\n        return {\"error\": \"Rate limit hit — retry after a moment\"}\n    except Exception as e:\n        return {\"error\": str(e)}\n",
+  "downloads": 0,
+  "created_at": 1710000010
+}

claude_extractor.json

@@ -0,0 +1,25 @@
+{
+  "id": "claude_extractor",
+  "name": "Claude Extractor",
+  "version": "1.0.0",
+  "description": "Extract structured data from unstructured text using Claude. Provide a schema and raw text; Claude returns a JSON object matching the schema. Perfect for parsing documents, emails, web pages, or any free-form input.",
+  "author": "Chris4K",
+  "tags": ["claude", "anthropic", "extraction", "nlp", "structured-output", "json"],
+  "runtime": "python",
+  "dependencies": ["anthropic"],
+  "env_required": ["ANTHROPIC_API_KEY"],
+  "schema": {
+    "input": {
+      "text": "str — raw text to extract from",
+      "schema": "dict — JSON schema describing what to extract, e.g. {name: str, date: str, amount: float}",
+      "instructions": "str — optional extra extraction instructions"
+    },
+    "output": {
+      "extracted": "dict — extracted fields matching the schema",
+      "raw_response": "str — Claude's full response (for debugging)"
+    }
+  },
+  "code": "import os\nimport json\nimport re\nfrom typing import Optional\n\n\ndef execute(\n    text: str,\n    schema: dict,\n    instructions: str = \"\",\n    api_key: Optional[str] = None,\n    model: str = \"claude-haiku-4-5-20251001\",\n) -> dict:\n    \"\"\"\n    Extract structured data from text using Claude.\n    Returns a dict matching the provided schema.\n    \"\"\"\n    try:\n        import anthropic\n    except ImportError:\n        return {\"error\": \"anthropic package not installed\"}\n\n    key = api_key or os.environ.get(\"ANTHROPIC_API_KEY\")\n    if not key:\n        return {\"error\": \"ANTHROPIC_API_KEY not set\"}\n\n    schema_str = json.dumps(schema, indent=2)\n    extra = f\"\\n\\nAdditional instructions: {instructions}\" if instructions else \"\"\n\n    system = (\n        \"You are a precise data extraction assistant. \"\n        \"Extract information from text and return ONLY valid JSON — no explanation, no markdown, no backticks. \"\n        \"If a field cannot be found in the text, use null.\"\n    )\n\n    prompt = f\"\"\"Extract data from the following text and return a JSON object matching this schema:\n\n{schema_str}{extra}\n\nText to extract from:\n---\n{text[:4000]}\n---\n\nReturn ONLY the JSON object, nothing else.\"\"\"\n\n    client = anthropic.Anthropic(api_key=key)\n    try:\n        msg = client.messages.create(\n            model=model,\n            max_tokens=1024,\n            system=system,\n            messages=[{\"role\": \"user\", \"content\": prompt}],\n        )\n        raw = msg.content[0].text.strip() if msg.content else \"{}\"\n\n        # Strip markdown fences if present\n        raw_clean = re.sub(r\"^```[a-z]*\\n?\", \"\", raw).rstrip(\"```\").strip()\n\n        try:\n            extracted = json.loads(raw_clean)\n        except json.JSONDecodeError:\n            extracted = {\"_parse_error\": raw_clean}\n\n        return {\n            \"extracted\": extracted,\n            \"raw_response\": raw,\n            \"model\": model,\n        }\n    except Exception as e:\n        return {\"error\": str(e)}\n",
+  "downloads": 0,
+  "created_at": 1710000011
+}

mcp_server.py

@@ -0,0 +1,253 @@
+"""
+FORGE MCP Server
+Exposes FORGE skills via Model Context Protocol (MCP)
+so Claude Desktop, Claude API, and any MCP client can use them natively.
+
+Endpoints:
+  GET  /mcp/sse          — SSE stream (for Claude Desktop / mcp-remote)
+  POST /mcp              — JSON-RPC 2.0 (for direct API calls)
+"""
+import json
+import asyncio
+import time
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import StreamingResponse, JSONResponse
+
+import skill_registry as registry
+
+# ── MCP Tool Definitions ──────────────────────────────────────────
+
+MCP_TOOLS = [
+    {
+        "name": "forge_list_skills",
+        "description": "List all skills available in the FORGE registry. Optionally filter by tag or search query.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "tag":   {"type": "string", "description": "Filter by tag (e.g. 'math', 'web', 'claude')"},
+                "query": {"type": "string", "description": "Text search across name, description, tags"},
+            },
+        },
+    },
+    {
+        "name": "forge_get_skill",
+        "description": "Get full metadata and executable code for a specific skill by ID.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "skill_id": {"type": "string", "description": "The skill ID, e.g. 'calculator'"},
+            },
+            "required": ["skill_id"],
+        },
+    },
+    {
+        "name": "forge_get_code",
+        "description": "Get only the executable Python code for a skill. Returns minimal payload for agent hot-loading.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "skill_id": {"type": "string", "description": "The skill ID"},
+            },
+            "required": ["skill_id"],
+        },
+    },
+    {
+        "name": "forge_search",
+        "description": "Search FORGE skills by keyword. Returns matching skills with descriptions and tags.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Search query"},
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "forge_get_stats",
+        "description": "Get FORGE registry statistics: total skills, downloads, top skills.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+        },
+    },
+    {
+        "name": "forge_publish_skill",
+        "description": "Publish a new skill to the FORGE registry. The skill must include id, name, version, description, author, tags, and code with a def execute() function.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "skill_json": {
+                    "type": "string",
+                    "description": "JSON string of the skill document to publish",
+                },
+            },
+            "required": ["skill_json"],
+        },
+    },
+]
+
+# ── Tool Dispatcher ───────────────────────────────────────────────
+
+def dispatch_tool(name: str, args: dict) -> Any:
+    if name == "forge_list_skills":
+        tag   = args.get("tag")
+        query = args.get("query")
+        skills = registry.list_skills(tag=tag, query=query)
+        return {
+            "count": len(skills),
+            "skills": [
+                {
+                    "id": s["id"],
+                    "name": s["name"],
+                    "version": s["version"],
+                    "description": s["description"],
+                    "tags": s.get("tags", []),
+                    "downloads": s.get("downloads", 0),
+                }
+                for s in skills
+            ],
+        }
+
+    elif name == "forge_get_skill":
+        skill_id = args.get("skill_id", "")
+        skill = registry.get_skill(skill_id)
+        if not skill:
+            return {"error": f"Skill '{skill_id}' not found"}
+        return skill
+
+    elif name == "forge_get_code":
+        skill_id = args.get("skill_id", "")
+        data = registry.get_skill_code(skill_id)
+        if not data:
+            return {"error": f"Skill '{skill_id}' not found"}
+        return data
+
+    elif name == "forge_search":
+        query  = args.get("query", "")
+        skills = registry.list_skills(query=query)
+        return {
+            "query": query,
+            "count": len(skills),
+            "skills": [{"id": s["id"], "name": s["name"], "description": s["description"], "tags": s.get("tags", [])} for s in skills],
+        }
+
+    elif name == "forge_get_stats":
+        return registry.get_stats()
+
+    elif name == "forge_publish_skill":
+        try:
+            skill = json.loads(args.get("skill_json", "{}"))
+        except json.JSONDecodeError as e:
+            return {"error": f"Invalid JSON: {e}"}
+        ok, msg = registry.publish_skill(skill)
+        return {"ok": ok, "message": msg}
+
+    else:
+        return {"error": f"Unknown tool: {name}"}
+
+
+# ── JSON-RPC 2.0 Handler ─────────────────────────────────────────
+
+def handle_jsonrpc(request_body: dict) -> dict:
+    method = request_body.get("method", "")
+    params = request_body.get("params", {})
+    req_id = request_body.get("id", 1)
+
+    def ok(result):
+        return {"jsonrpc": "2.0", "id": req_id, "result": result}
+
+    def err(code, message):
+        return {"jsonrpc": "2.0", "id": req_id, "error": {"code": code, "message": message}}
+
+    # MCP lifecycle
+    if method == "initialize":
+        return ok({
+            "protocolVersion": "2024-11-05",
+            "capabilities": {"tools": {"listChanged": False}},
+            "serverInfo": {
+                "name": "forge",
+                "version": "1.0.0",
+                "description": "FORGE — Federated Open Registry for Generative Executables. Skill artifactory for AI agents.",
+            },
+        })
+
+    elif method == "tools/list":
+        return ok({"tools": MCP_TOOLS})
+
+    elif method == "tools/call":
+        tool_name = params.get("name", "")
+        tool_args  = params.get("arguments", {})
+        result     = dispatch_tool(tool_name, tool_args)
+        return ok({
+            "content": [{"type": "text", "text": json.dumps(result, indent=2, ensure_ascii=False)}]
+        })
+
+    elif method == "ping":
+        return ok({})
+
+    else:
+        return err(-32601, f"Method not found: {method}")
+
+
+# ── FastAPI Routes ────────────────────────────────────────────────
+
+def register_mcp_routes(app: FastAPI):
+
+    @app.post("/mcp")
+    async def mcp_jsonrpc(request: Request):
+        try:
+            body = await request.json()
+        except Exception:
+            return JSONResponse(
+                {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "Parse error"}},
+                status_code=400,
+            )
+        response = handle_jsonrpc(body)
+        return JSONResponse(response)
+
+    @app.get("/mcp/sse")
+    async def mcp_sse(request: Request):
+        """
+        SSE endpoint for Claude Desktop / mcp-remote clients.
+        Streams MCP messages over Server-Sent Events.
+        """
+        async def event_stream():
+            # Send server info on connect
+            server_info = json.dumps({
+                "jsonrpc": "2.0",
+                "method": "notifications/initialized",
+                "params": {
+                    "serverInfo": {
+                        "name": "forge",
+                        "version": "1.0.0",
+                    },
+                    "tools": MCP_TOOLS,
+                },
+            })
+            yield f"event: message\ndata: {server_info}\n\n"
+
+            # Keep alive
+            try:
+                while True:
+                    if await request.is_disconnected():
+                        break
+                    yield f"event: ping\ndata: {json.dumps({'ts': int(time.time())})}\n\n"
+                    await asyncio.sleep(15)
+            except asyncio.CancelledError:
+                pass
+
+        return StreamingResponse(
+            event_stream(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    @app.get("/mcp/tools")
+    async def mcp_tools_list():
+        """Quick HTTP endpoint listing all MCP tools (non-SSE)."""
+        return JSONResponse({"tools": MCP_TOOLS, "count": len(MCP_TOOLS)})

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=4.44.0
+fastapi>=0.111.0
+uvicorn>=0.30.0
+requests>=2.31.0
+anthropic>=0.40.0

skill_registry.py

@@ -0,0 +1,231 @@
+"""
+FORGE — Skill Registry Core
+Handles loading, validation, search, and serving of skills.
+"""
+import json
+import os
+import re
+import time
+from pathlib import Path
+from typing import Optional
+
+SKILLS_DIR = Path(__file__).parent / "skills"
+
+REQUIRED_FIELDS = {"id", "name", "version", "description", "author", "tags", "code"}
+
+# ─────────────────────────────────────────────
+# Internal helpers
+# ─────────────────────────────────────────────
+
+def _load_skill_file(path: Path) -> dict | None:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if REQUIRED_FIELDS.issubset(data.keys()):
+            data.setdefault("downloads", 0)
+            data.setdefault("created_at", int(path.stat().st_mtime))
+            return data
+    except Exception:
+        pass
+    return None
+
+
+def _save_skill_file(skill: dict):
+    path = SKILLS_DIR / f"{skill['id']}.json"
+    path.write_text(json.dumps(skill, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+# ─────────────────────────────────────────────
+# Public API
+# ─────────────────────────────────────────────
+
+def list_skills(tag: Optional[str] = None, query: Optional[str] = None) -> list[dict]:
+    """Return all skills (stripped of code), optionally filtered."""
+    skills = []
+    for path in sorted(SKILLS_DIR.glob("*.json")):
+        skill = _load_skill_file(path)
+        if skill is None:
+            continue
+        if tag and tag.lower() not in [t.lower() for t in skill.get("tags", [])]:
+            continue
+        if query:
+            q = query.lower()
+            searchable = f"{skill['name']} {skill['description']} {' '.join(skill.get('tags', []))}"
+            if q not in searchable.lower():
+                continue
+        skills.append({k: v for k, v in skill.items() if k != "code"})
+    return skills
+
+
+def get_skill(skill_id: str) -> dict | None:
+    """Return full skill including code."""
+    path = SKILLS_DIR / f"{skill_id}.json"
+    if not path.exists():
+        return None
+    skill = _load_skill_file(path)
+    if skill:
+        # bump download count
+        skill["downloads"] = skill.get("downloads", 0) + 1
+        _save_skill_file(skill)
+    return skill
+
+
+def get_skill_code(skill_id: str) -> dict | None:
+    """Return just the code + minimal meta for agent consumption."""
+    skill = get_skill(skill_id)
+    if not skill:
+        return None
+    return {
+        "id": skill["id"],
+        "version": skill["version"],
+        "dependencies": skill.get("dependencies", []),
+        "schema": skill.get("schema", {}),
+        "code": skill["code"],
+    }
+
+
+def get_manifest() -> dict:
+    """Full manifest for agent bootstrap — includes code for all skills."""
+    skills = []
+    for path in sorted(SKILLS_DIR.glob("*.json")):
+        skill = _load_skill_file(path)
+        if skill:
+            skills.append(skill)
+    return {
+        "forge_version": "1.0.0",
+        "generated_at": int(time.time()),
+        "skill_count": len(skills),
+        "skills": skills,
+    }
+
+
+def get_all_tags() -> list[str]:
+    tags: set[str] = set()
+    for path in SKILLS_DIR.glob("*.json"):
+        skill = _load_skill_file(path)
+        if skill:
+            tags.update(skill.get("tags", []))
+    return sorted(tags)
+
+
+def publish_skill(skill: dict) -> tuple[bool, str]:
+    """Validate and save a new skill. Returns (ok, message)."""
+    missing = REQUIRED_FIELDS - set(skill.keys())
+    if missing:
+        return False, f"Missing required fields: {missing}"
+
+    # Validate ID format
+    if not re.match(r"^[a-z][a-z0-9_]{1,48}[a-z0-9]$", skill["id"]):
+        return False, "ID must be lowercase alphanumeric + underscores, 3-50 chars"
+
+    # Check execute() is present
+    if "def execute(" not in skill["code"]:
+        return False, "Skill code must contain a def execute(...) function"
+
+    # Don't overwrite existing (use versioning)
+    path = SKILLS_DIR / f"{skill['id']}.json"
+    if path.exists():
+        existing = _load_skill_file(path)
+        if existing and existing.get("version") == skill.get("version"):
+            return False, f"Version {skill['version']} of '{skill['id']}' already exists"
+
+    skill["created_at"] = int(time.time())
+    skill["downloads"] = 0
+    _save_skill_file(skill)
+    return True, f"Skill '{skill['id']}' v{skill['version']} published successfully"
+
+
+def update_skill(skill_id: str, updates: dict) -> tuple[bool, str]:
+    """Update fields of an existing skill. Bumps version if code changes."""
+    path = SKILLS_DIR / f"{skill_id}.json"
+    if not path.exists():
+        return False, f"Skill '{skill_id}' not found"
+    existing = _load_skill_file(path)
+    if not existing:
+        return False, f"Failed to load skill '{skill_id}'"
+
+    # Prevent ID change via update
+    updates.pop("id", None)
+    updates.pop("created_at", None)
+    updates.pop("downloads", None)
+
+    existing.update(updates)
+    existing["updated_at"] = int(time.time())
+    _save_skill_file(existing)
+    return True, f"Skill '{skill_id}' updated"
+
+
+def delete_skill(skill_id: str) -> tuple[bool, str]:
+    """Delete a skill from the registry."""
+    path = SKILLS_DIR / f"{skill_id}.json"
+    if not path.exists():
+        return False, f"Skill '{skill_id}' not found"
+    # Archive before deletion
+    archive = SKILLS_DIR / f"{skill_id}.deleted.json"
+    path.rename(archive)
+    return True, f"Skill '{skill_id}' deleted"
+
+
+def parse_skill_md(content: str) -> tuple[dict | None, str]:
+    """
+    Parse a SKILL.md file (ClawHub-compatible format) into a FORGE skill dict.
+    Returns (skill_dict, error_message).
+    SKILL.md frontmatter (YAML between --- delimiters) + markdown body.
+    """
+    import re
+
+    # Extract YAML frontmatter
+    fm_match = re.match(r"^---\s*\n(.*?)\n---\s*\n?(.*)", content, re.DOTALL)
+    if not fm_match:
+        return None, "No YAML frontmatter found. SKILL.md must start with ---"
+
+    yaml_str, body = fm_match.group(1), fm_match.group(2)
+
+    # Simple YAML parser (avoid pyyaml dependency)
+    meta = {}
+    for line in yaml_str.splitlines():
+        if ":" in line:
+            k, _, v = line.partition(":")
+            k = k.strip()
+            v = v.strip().strip('"').strip("'")
+            # Handle list values: [a, b, c]
+            if v.startswith("[") and v.endswith("]"):
+                v = [x.strip().strip('"').strip("'") for x in v[1:-1].split(",") if x.strip()]
+            meta[k] = v
+
+    required = {"name", "version", "description"}
+    missing = required - set(meta.keys())
+    if missing:
+        return None, f"Missing required frontmatter fields: {missing}"
+
+    # Build skill ID from name
+    import re as _re
+    skill_id = _re.sub(r"[^a-z0-9_]", "_", meta["name"].lower()).strip("_")
+
+    skill = {
+        "id": meta.get("id", skill_id),
+        "name": meta["name"],
+        "version": meta.get("version", "1.0.0"),
+        "description": meta["description"],
+        "author": meta.get("author", "unknown"),
+        "tags": meta.get("tags", []) if isinstance(meta.get("tags"), list) else [meta.get("tags", "instructions")],
+        "runtime": meta.get("runtime", "instructions"),
+        "dependencies": [],
+        "schema": {},
+        # SKILL.md skills store markdown body as "instructions" (not executable code)
+        "instructions": body.strip(),
+        # Minimal execute() wrapper that returns the instructions
+        "code": f'def execute(**kwargs) -> dict:\n    """SKILL.md instruction skill — returns the instructions for the agent."""\n    return {{"instructions": """{body.strip()[:500]}""", "runtime": "instructions"}}',
+    }
+    return skill, ""
+
+
+def get_stats() -> dict:
+    skills = list_skills()
+    total_downloads = sum(s.get("downloads", 0) for s in skills)
+    all_tags = get_all_tags()
+    return {
+        "total_skills": len(skills),
+        "total_downloads": total_downloads,
+        "total_tags": len(all_tags),
+        "top_skills": sorted(skills, key=lambda x: x.get("downloads", 0), reverse=True)[:5],
+    }