openspace

OpenSpace: Self-Evolving Skill System

What it does: OpenSpace is a self-evolving engine that makes AI agents smarter and more cost-efficient. Skills automatically learn, fix themselves, and improve over time. One agent's improvement becomes every agent's upgrade through cloud skill sharing.

Core Capabilities

🧬 Self-Evolution

AUTO-FIX — When a skill breaks, it fixes itself instantly
AUTO-IMPROVE — Successful patterns become better skill versions
AUTO-LEARN — Captures winning workflows from actual usage
Quality monitoring — Tracks skill performance, error rates, execution success

🌐 Collective Intelligence

Shared evolution — One agent's improvement becomes every agent's upgrade
Network effects — More agents → richer data → faster evolution
Easy sharing — Upload and download evolved skills with one command
Access control — Public, private, or team-only access per skill

💰 Token Efficiency

46% fewer tokens through skill reuse and evolution
4.2× better performance on real-world professional tasks
Stop repeating work → Reuse successful solutions
Small updates only → Fix what's broken, don't rebuild everything

CLI vs MCP: Token-Saving Priority

ALWAYS try CLI first. MCP tools consume tokens through protocol overhead; CLI calls via Bash are token-free beyond the command itself.

Priority Order:

1. OpenSpace CLI → Direct Bash execution (token-free)
2. OpenSpace MCP → Protocol overhead (use when CLI insufficient)

When to use CLI (Primary):

✅ Task execution: openspace --query "task description"
✅ Skill download: openspace-download-skill <skill_id>
✅ Skill upload: openspace-upload-skill /path/to/skill/dir
✅ Quick task execution without needing structured results back

When to escalate to MCP (Backup):

⬆️ Need structured output parsed into conversation context
⬆️ Multi-step workflows where MCP state persistence helps
⬆️ Integration with other MCP tools in a single flow
⬆️ Automatic skill evolution tracking across tool calls
⬆️ Need result objects for conditional logic

CLI saves ~200-500 tokens per call compared to MCP. Over 20 OpenSpace calls, that's 4K-10K tokens saved.

When to Use OpenSpace

Use OpenSpace for:

✅ Complex multi-step tasks that would benefit from evolved, battle-tested workflows
✅ Repeated similar tasks where skill evolution can save tokens over time
✅ Tasks with unclear approaches — OpenSpace can search and apply community skills
✅ Skill evolution — automatically fix broken skills or derive improved versions
✅ Knowledge sharing — upload successful patterns or download community skills

Don't use OpenSpace for:

❌ Simple one-off tasks with clear solutions
❌ Tasks that already have well-defined local skills
❌ Quick reads, simple calculations, or trivial operations

CLI Commands (Use These First)

OpenSpace provides a standalone CLI for token-free execution:

# Execute a task
openspace --query "Create a monitoring dashboard for Docker containers"

# Download a skill from cloud
openspace-download-skill <skill_id>

# Upload a skill to cloud
openspace-upload-skill /path/to/skill/dir

# Local dashboard (optional)
openspace-dashboard --port 7788

CLI examples:

# Task execution
openspace --query "Generate a Python script to process CSV files"

# Download and use community skill
openspace-download-skill sk_abc123xyz

Search is MCP-only — use mcp__openspace__search_skills tool:

# Search via MCP tool (not CLI)
mcp__openspace__search_skills(
    query="csv processing",
    source="all",  # local + cloud
    limit=10
)

Available MCP Tools (Use as Backup)

OpenSpace exposes 4 MCP tools via the openspace MCP server when CLI is insufficient:

1. `mcpopenspaceexecute_task`

Execute complex tasks through OpenSpace's grounding agent with automatic skill evolution.

Parameters:

task (required) — Task description in natural language
max_iterations (optional, default: 20) — Maximum reasoning loops
search_scope (optional, default: "all") — "local", "cloud", or "all"

When to use:

Multi-step tasks requiring tool orchestration
Tasks that might benefit from evolved skills
Complex workflows that Claude Code struggles with

Returns:

response — Task result/summary
evolved_skills — List of skills that evolved during execution (FIX/DERIVED/CAPTURED)
status — "completed" or "failed"

2. `mcpopenspacesearch_skills`

Search for skills in local registry and cloud community.

Parameters:

query (required) — Search query (natural language or keywords)
scope (optional, default: "all") — "local", "cloud", or "all"
top_k (optional, default: 5) — Number of results to return

When to use:

Before starting a complex task — check if community skills exist
Discovering reusable patterns for common workflows
Finding specialized skills for specific domains

Returns:

List of matching skills with:
- name — Skill name
- description — What it does
- source — "local" or "cloud"
- skill_id — Unique identifier (for cloud skills)

3. `mcpopenspacefix_skill`

Repair a broken or outdated skill.

Parameters:

skill_name (required) — Name of the skill to fix
error_context (optional) — Error message or failure context
suggestion (optional) — Specific fix suggestion

When to use:

A skill failed due to API changes or outdated instructions
Tool behavior changed and skill needs updating
You notice a skill producing incorrect results

Returns:

success — Boolean indicating if fix succeeded
new_version — Version number of the fixed skill
diff — Changes made to the skill

4. `mcpopenspaceupload_skill`

Upload a skill to the cloud community.

Parameters:

skill_dir (required) — Path to skill directory
visibility (optional, default: "private") — "public", "private", or "group"
group_id (optional) — Group ID for group-only sharing

When to use:

You've created or evolved a valuable skill worth sharing
You want to back up a skill to the cloud
Sharing skills within a team/group

Requires: OPENSPACE_API_KEY in environment

Returns:

skill_id — Cloud skill identifier
url — Skill URL on open-space.cloud

Host Skills Integration

Two host skills are automatically installed to .claude/skills/:

1. delegate-task

Teaches Claude Code when and how to delegate complex tasks to OpenSpace.

Teaches:

When to use execute_task vs handling directly
How to interpret OpenSpace results
When to trigger skill evolution (fix_skill)
How to upload successful patterns (upload_skill)

2. skill-discovery

Teaches Claude Code how to search and discover skills before starting work.

Teaches:

When to search for skills (before complex tasks)
How to evaluate search results (local vs cloud)
Decision: follow skill yourself, delegate to OpenSpace, or skip
How to import cloud skills to local registry

Skill Evolution Modes

OpenSpace evolves skills in three ways:

🔧 FIX

Repairs broken or outdated instructions in-place. Same skill, new version.

Triggers:

Skill execution failure
Tool degradation (success rate drops)
API/tool behavior changes

🚀 DERIVED

Creates enhanced or specialized versions from parent skills. New skill directory.

Triggers:

Successful pattern improvement opportunity
Specialization for specific use case
Combination of multiple complementary skills

✨ CAPTURED

Extracts novel reusable patterns from successful executions. Brand new skill.

Triggers:

Novel workflow emerges from multi-step execution
Repeatable pattern identified across tasks
Successful recovery strategy worth preserving

Environment Configuration

Required:

Python 3.12+
pip install -e tools/openspace (auto-handled by setup.sh)

Optional:

OPENSPACE_API_KEY — Cloud skill access (register at https://open-space.cloud)
OPENSPACE_WORKSPACE — Custom workspace path (default: tools/openspace)
OPENSPACE_DEBUG — Enable debug logging

LLM credentials auto-detected from:

Provider-native env vars (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
OPENSPACE_LLM_* overrides (if needed)

Workflow Example

Before OpenSpace:

User: "Create a monitoring dashboard for Docker containers"
Claude: [Reasons from scratch, writes code, debugs, 50K tokens]

With OpenSpace:

User: "Create a monitoring dashboard for Docker containers"
Claude: [Searches skills via skill-discovery]
  → Found: docker-monitoring, dashboard-layout-v3, data-polling
  → Delegates to execute_task
OpenSpace: [Applies evolved skills, auto-fixes issues, 27K tokens]
  → Returns: Working dashboard
  → CAPTURED: docker-stats-api-fallback (new skill)

Next similar task:

User: "Create a monitoring dashboard for system processes"
Claude: [Searches skills]
  → Found: docker-stats-api-fallback (from previous task)
  → DERIVED: process-stats-api (specialized version)
OpenSpace: [Applies derived skill, 15K tokens]

Quality Monitoring

OpenSpace tracks:

Skill metrics — Applied rate, completion rate, effective rate, fallback rate
Tool metrics — Success rate, latency, flagged issues
Code execution — Status, error patterns

Auto-triggers evolution when:

Tool success rates drop below threshold
Skill completion rates decline
Error patterns emerge across multiple executions
Manual evolution requested via fix_skill

Cloud Skill Community

Browse: https://open-space.cloud (no account needed)

Register: Get OPENSPACE_API_KEY to:

Upload evolved skills (public/private/group)
Access private/group skills
Track skill lineage and evolution
View performance metrics

CLI tools:

# Download a skill from cloud
openspace-download-skill <skill_id>

# Upload a skill to cloud
openspace-upload-skill /path/to/skill/dir

Dashboard (Optional)

Local web UI to browse skills, track lineage, compare diffs.

Requirements: Node.js ≥ 20

Start:

# Terminal 1: Backend API
openspace-dashboard --port 7788

# Terminal 2: Frontend dev server
cd tools/openspace/frontend
npm install        # first time only
npm run dev

Features:

Browse local and cloud skills
View evolution lineage graphs
Compare skill diffs between versions
Track workflow session history
Monitor skill performance metrics

Troubleshooting

"Missing environment variables"

Ensure LLM API key is set (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
For cloud features, add OPENSPACE_API_KEY

"Skill not found"

Check search_scope parameter (local/cloud/all)
Verify skill was registered to local registry
For cloud skills, ensure OPENSPACE_API_KEY is valid

"Evolution failed"

Check execution logs in tools/openspace/logs/
Verify skill directory structure (must have SKILL.md)
Ensure diff-based patches are valid

"MCP server timeout"

Increase toolTimeout in .mcp.json (default: 600s)
Long evolutions may need 1200s+
Check if evolution confirmation is hanging (requires user input)

Performance Benchmarks

From GDPVal benchmark (50 professional tasks, 6 industries):

Metric	Result
Income vs Baseline	4.2× higher (same LLM)
Token Reduction	46% fewer tokens (Phase 2 vs Phase 1)
Quality Improvement	+30pp above best baseline
Value Capture	72.8% ($11,484 / $15,764)

Task categories improved:

Documents & Correspondence: +3.3pp quality, −56% tokens
Compliance & Forms: +18.5pp quality, −51% tokens
Media Production: +5.8pp quality, −46% tokens
Engineering: +8.7pp quality, −43% tokens
Spreadsheets: +7.3pp quality, −37% tokens
Strategy & Analysis: +1.0pp quality, −32% tokens

165 skills evolved across benchmark, with most focusing on:

File format I/O (44 skills)
Execution recovery (29 skills)
Document generation (26 skills)
Quality assurance (23 skills)

Source & Documentation

GitHub: https://github.com/HKUDS/OpenSpace (13K+ stars)
Cloud Platform: https://open-space.cloud
Full README: tools/openspace/README.md
Config Guide: tools/openspace/openspace/config/README.md
Benchmark Details: tools/openspace/gdpval_bench/README.md

Bottom Line

OpenSpace turns individual agent learning into collective intelligence. Every task makes every agent smarter and more cost-efficient. Skills evolve automatically, agents share improvements, and token costs drop over time.

Use it when the task is complex enough that evolved, battle-tested workflows will save time and tokens compared to reasoning from scratch.

About this skill

Core Capabilities

🧬 Self-Evolution

🌐 Collective Intelligence

💰 Token Efficiency

CLI vs MCP: Token-Saving Priority

Priority Order:

When to use CLI (Primary):

When to escalate to MCP (Backup):

When to Use OpenSpace

CLI Commands (Use These First)

Available MCP Tools (Use as Backup)

1. mcp__openspace__execute_task

2. mcp__openspace__search_skills

3. mcp__openspace__fix_skill

4. mcp__openspace__upload_skill

Host Skills Integration

1. delegate-task

2. skill-discovery

Skill Evolution Modes

🔧 FIX

🚀 DERIVED

✨ CAPTURED

Environment Configuration

Workflow Example

Quality Monitoring

Cloud Skill Community

Dashboard (Optional)

Troubleshooting

Performance Benchmarks

Source & Documentation

Bottom Line

1. `mcpopenspaceexecute_task`

2. `mcpopenspacesearch_skills`

3. `mcpopenspacefix_skill`

4. `mcpopenspaceupload_skill`