Spaces:

Chris4K
/

agent-forge-bak

Sleeping

App Files Files Community

agent-forge-bak / HowTo.md

Chris4K

Create HowTo.md

d0a1a60 verified 6 days ago

preview code

raw

history blame contribute delete

11.5 kB

⚒️ FORGE — Complete How-To Guide

What is FORGE?
vs ClawHub
Deploy to HuggingFace
Skill Formats
CRUD — Create, Read, Update, Delete
MCP Server — Claude native integration
Bins & Node Tools
Claude Skills (Anthropic API)
Agent Quick Start
REST API Reference

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)

# 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.

{
  "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.

---
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.

{
  "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:

curl -X POST https://YOUR_SPACE.hf.space/api/v1/skills \
  -H "Content-Type: application/json" \
  -d @my_skill.json

Via Python agent:

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):

GET /api/v1/skills/calculator

Read skill code (for hot-loading):

GET /api/v1/skills/calculator/code

Download as .py file:

GET /api/v1/skills/calculator/download

Full manifest (all skills + code for offline cache):

GET /api/v1/manifest

Search:

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:

{
  "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:

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:

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOUR_SPACE.hf.space/mcp/sse"]
    }
  }
}

Or via the API with SSE:

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:

{
  "id": "pdf_extractor",
  "runtime": "python",
  "bins": ["pdftotext", "gs"],
  "dependencies": ["pypdf2"],
  "install_notes": "apt-get install poppler-utils ghostscript",
  "code": "..."
}

{
  "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

{
  "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

{
  "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

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

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