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. mcp__openspace__execute_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. mcp__openspace__search_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. mcp__openspace__fix_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. mcp__openspace__upload_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:

1. Provider-native env vars (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
2. 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):

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.