OpenSpace: Self-Evolving Agent Skills

---
name: openspace-self-evolving-agents
description: Skill for using OpenSpace to make AI agents smarter, lower-cost, and self-evolving through skill sharing and collective intelligence.
triggers:
  - add OpenSpace to my agent
  - make my agent self-evolving
  - reduce agent token costs
  - share skills between agents
  - plug OpenSpace into Claude Code
  - set up skill evolution for my AI agent
  - use OpenSpace MCP server
  - evolve agent skills automatically
---

# OpenSpace: Self-Evolving Agent Skills

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

OpenSpace is a self-evolving engine that plugs into any MCP-compatible AI agent (Claude Code, Codex, OpenClaw, nanobot, Cursor, etc.) and gives it three superpowers: **self-evolving skills** (auto-fix, auto-improve, auto-learn), **collective agent intelligence** (shared skill community), and **token efficiency** (46% fewer tokens, 4.2× better economic output on real-world tasks).

---

## Installation

git clone https://github.com/HKUDS/OpenSpace.git && cd OpenSpace

pip install -e .

openspace-mcp --help # verify installation

Node.js ≥ 20 is required only for the local dashboard frontend.

---

## Two Usage Paths

### Path A — Plug Into Your Agent (MCP)

Add OpenSpace as an MCP server in your agent's config file:

{

"mcpServers": {

"openspace": {

"command": "openspace-mcp",

"toolTimeout": 600,

"env": {

"OPENSPACE_HOST_SKILL_DIRS": "/path/to/your/agent/skills",

"OPENSPACE_WORKSPACE": "/path/to/OpenSpace",

"OPENSPACE_API_KEY": "$OPENSPACE_API_KEY"

}

}

}

}

Then copy the two bootstrap host skills into your agent's skills directory:

cp -r OpenSpace/openspace/host_skills/delegate-task/ /path/to/your/agent/skills/

cp -r OpenSpace/openspace/host_skills/skill-discovery/ /path/to/your/agent/skills/

These two skills teach the agent **when and how** to use OpenSpace — no additional prompting needed.

- `delegate-task` — delegate complex tasks to OpenSpace for execution with evolved skills
- `skill-discovery` — let the agent search for and download community skills

> Credentials (LLM API key, model) are auto-detected from the agent's own config. `OPENSPACE_API_KEY` is optional — local features work without it.

### Path B — Use OpenSpace Directly as a Co-Worker

Create a `.env` file (see `openspace/.env.example`):

# openspace/.env

ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY # or OPENAI_API_KEY, etc.

OPENSPACE_API_KEY=$OPENSPACE_API_KEY # optional, for cloud community

Then run interactively or with a query:

# Interactive REPL

openspace

# One-shot task

openspace --model "anthropic/claude-sonnet-4-5" \

--query "Create a monitoring dashboard for my Docker containers"

---

## Python API

import asyncio

from openspace import OpenSpace

async def main():

async with OpenSpace() as cs:

# Execute a task — skills evolve automatically

result = await cs.execute(

"Analyze GitHub trending repos and create a report"

)

print(result["response"])

# Inspect which skills evolved during this session

for skill in result.get("evolved_skills", []):

print(f" Evolved: {skill['name']} (origin: {skill['origin']})")

asyncio.run(main())

### Execute with a specific model

import asyncio

from openspace import OpenSpace

async def run_task():

async with OpenSpace(model="openai/gpt-4o") as cs:

result = await cs.execute(

"Build a payroll calculator from this union contract PDF"

)

print(result["response"])

print(f"Tokens used: {result.get('token_usage')}")

asyncio.run(run_task())

---

## CLI Reference

| Command | Description |
|---|---|
| `openspace` | Interactive agent REPL |
| `openspace --query "..."` | Execute a single task |
| `openspace --model "provider/model"` | Specify LLM model |
| `openspace-mcp` | Start the MCP server (for agent integration) |
| `openspace-dashboard --port 7788` | Start local dashboard API backend |
| `openspace-download-skill <skill_id>` | Download a skill from the cloud community |
| `openspace-upload-skill /path/to/skill/` | Upload a local skill to the cloud community |

---

## Cloud Skill Community

Register at [open-space.cloud](https://open-space.cloud) to get an API key, then set it in env:

export OPENSPACE_API_KEY="$OPENSPACE_API_KEY"

Or add to `.env`:

OPENSPACE_API_KEY=$OPENSPACE_API_KEY

### Download a community skill

openspace-download-skill skill_abc123

### Upload an evolved skill

openspace-upload-skill ./openspace/skills/my-evolved-skill/

Skills can be set to **public**, **private**, or **team-only** access.

---

## Local Dashboard

Visualize skill evolution lineage, browse versions, compare diffs, and inspect execution sessions.

# Terminal 1 — backend API

openspace-dashboard --port 7788

# Terminal 2 — frontend dev server

cd frontend

npm install # only once

npm run dev # opens at http://localhost:5173

Dashboard panels:
- **Skill Classes** — browse, search, and sort all local skills
- **Cloud** — discover community skill records
- **Version Lineage** — visual evolution graph per skill
- **Workflow Sessions** — execution history and token metrics

---

## Writing Custom Skills

Skills live as directories under `openspace/skills/`. Each skill directory contains:

my-skill/

SKILL.md # skill description and usage instructions

skill.py # implementation (Python)

requirements.txt # optional dependencies

See `openspace/skills/README.md` for the full authoring guide.

Example minimal skill:

# openspace/skills/fetch-url/skill.py

import httpx

async def fetch_url(url: str) -> dict:

"""Fetch content from a URL and return text and status."""

async with httpx.AsyncClient(timeout=30) as client:

response = await client.get(url)

return {

"status": response.status_code,

"text": response.text[:4000],

"url": url,

}

---

## Environment Variables Reference

| Variable | Required | Description |
|---|---|---|
| `OPENSPACE_HOST_SKILL_DIRS` | For Path A | Path to agent's skills directory |
| `OPENSPACE_WORKSPACE` | For Path A | Path to OpenSpace repo root |
| `OPENSPACE_API_KEY` | Optional | Cloud community access key |
| `ANTHROPIC_API_KEY` | If using Claude | Anthropic API key |
| `OPENAI_API_KEY` | If using OpenAI | OpenAI API key |

All env vars can be set in `openspace/.env` (copy from `openspace/.env.example`).

---

## Common Patterns

### Pattern: Delegate a complex multi-step task

async with OpenSpace() as cs:

result = await cs.execute(

"Prepare a tax return summary from the 15 PDFs in ./documents/tax/"

)

# OpenSpace selects or evolves the right skills automatically

print(result["response"])

### Pattern: Reuse evolved skills across agents

# Agent A evolves a skill, upload it

openspace-upload-skill ./openspace/skills/tax-return-summarizer/

# Agent B downloads and uses it immediately

openspace-download-skill skill_tax_return_abc123

### Pattern: Monitor skill quality

Skills auto-track: performance, error rates, and execution success. View in the dashboard or query programmatically:

async with OpenSpace() as cs:

result = await cs.execute("Show skill performance metrics for the last 7 days")

print(result["response"])

---

## Per-Agent MCP Configuration

### Claude Code (`claude_desktop_config.json` or `.claude/mcp.json`)

{

"mcpServers": {

"openspace": {

"command": "openspace-mcp",

"toolTimeout": 600,

"env": {

"OPENSPACE_HOST_SKILL_DIRS": "/Users/me/.claude/skills",

"OPENSPACE_WORKSPACE": "/Users/me/OpenSpace",

"OPENSPACE_API_KEY": "$OPENSPACE_API_KEY"

}

}

}

}

### Codex / OpenClaw / nanobot

Follow the same MCP config pattern — consult `openspace/host_skills/README.md` for agent-specific paths and any extra flags.

---

## Troubleshooting

**`openspace-mcp` not found after install**

pip install -e . # re-run from repo root

which openspace-mcp

**Skills not evolving / auto-fix not triggering**
- Ensure both `delegate-task` and `skill-discovery` host skills are copied to your agent's skills directory.
- Check that `OPENSPACE_WORKSPACE` points to the repo root (where `openspace/skills/` lives).

**Cloud upload/download fails**
- Verify `OPENSPACE_API_KEY` is set and valid (register at [open-space.cloud](https://open-space.cloud)).
- Check network connectivity to the cloud endpoint.

**Dashboard frontend won't start**
- Node.js ≥ 20 is required: `node --version`
- Run `npm install` inside the `frontend/` directory before `npm run dev`.

**LLM credentials not picked up**
- OpenSpace auto-detects credentials from the host agent's environment. If running standalone (Path B), set keys in `openspace/.env`.

---

## Related Projects

- [ClawWork](https://github.com/HKUDS/ClawWork) — evaluation protocol used in GDPVal benchmark
- [nanobot](https://github.com/HKUDS/nanobot) — lightweight agent compatible with OpenSpace
- [OpenClaw](https://github.com/openclaw/openclaw) — agent framework compatible with OpenSpace
- [GDPVal dataset](https://huggingface.co/datasets/openai/gdpval) — 220 real-world professional tasks benchmark
- Community & skill browser: [open-space.cloud](https://open-space.cloud)