HOWTO.md

# ⚒️ 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*