DOCSEARCHbyAlgolia
Submit Docs

OpenSpace Documentation

repository·main·Indexed 27 days ago

https://github.com/hkuds/openspace

OpenSpace version 2.0.0 is a skill management layer for AI agents that enables the retrieval, evaluation, sharing, and evolution of skills based on real-world task outcomes. It features a local-first private infrastructure, a management dashboard for inspecting skill lineage and workflows, and support for the GDPVal and Terminal-Bench 2.1 benchmarks. The system includes a three-tier LLM credential resolution priority, MCP server registration, and configurable task runtime contexts.

Tokens
276K
Snippets
546
Records
1K
Agent score
92%

What's inside OpenSpace

  1. Overview of OpenSpace Skill Management

    main

    OpenSpace is a Skill Management Layer designed for AI agents (such as Claude Code, Codex, OpenClaw, Hermès, and nanobot). It addresses the challenges of skill retrieval, quality assessment, and evolution in growing agent libraries.

    OpenSpace provides four core capabilities:

    • Retrieve: Find the appropriate skill for any given task.
    • Evaluate: Use real-world task outcomes to determine which skills are effective.
    • Share: Convert successful workflows into reusable team knowledge.
    • Evolve: Continuously improve skills based on performance data.

    It supports a local-first approach, allowing organizations to deploy OpenSpace privately to maintain full control over workflows, data, and skill assets.

  2. Overview of OpenSpace Skill Hub

    main

    OpenSpace is a Skill Management Layer designed for AI Agents (such as Claude Code, Codex, Cursor, OpenClaw, and nanobot). It focuses on quality-driven skill management rather than mere quantity.

    Key capabilities include:

    • Real-task validation: Verifying skill effectiveness using evidence from actual tasks.
    • Evidence-driven evolution: Controlled skill evolution based on usage data.
    • Hierarchical Skill Hub: A structured way to organize and browse skills.
    • Full quality tracking: Maintaining quality records throughout the skill lifecycle.

  3. Use the docx-shell-workaround skill

    main

    The docx-shell-workaround skill provides a reliable fallback for handling .docx files when standard tools like read_file or execute_code_sandbox fail. It uses shell-based XML extraction and python-docx via run_shell to read and create Word documents.

    When to use this skill:

    • read_file cannot extract content from .docx files.
    • execute_code_sandbox encounters failures when creating or modifying .docx files.
    • You need a reliable fallback for .docx file manipulation.

  4. Understand OpenSpace v2 Core Capabilities

    main

    OpenSpace v2 is a quality-centric Skill Hub designed for AI Agents. It provides four primary capabilities to manage agent skills through real-world task evidence:

    1. Skill Quality Assessment: Determines skill utility based on real task results (e.g., whether a skill was selected, applied, completed, or resulted in a fallback) and tool reliability.
    2. Controlled Skill Evolution: Enables evidence-driven updates. New skills are marked as provisional and only promoted to trusted after successful cross-task performance. It supports version history and controlled replacement of old versions.
    3. Local-First Skill Hub: Supports a local-first workflow where agents run, search, and evolve skills locally. Cloud skills are organized into packages and are explicitly imported into the local skill folder before reuse.
    4. Agent Harness with Quality Records: Provides an execution environment that generates evidence for quality assessment. It includes recoverable sessions (task history, tool results, files), permission-aware tools, and a unified runtime boundary across CLI, Python API, MCP, gateway, and dashboard.

  5. Use the document-python-direct skill for document and spreadsheet tasks

    main

    The document-python-direct skill is designed for reliable spreadsheet manipulation and document/PDF generation. It is preferred over standard shell_agent tools when operations are complex, involve multiple steps, or require specific libraries like openpyxl, pandas, reportlab, or fpdf2. Using this skill avoids agent step limits and parsing errors associated with complex heredocs.

    When to use:

    • Reading/writing complex Excel files (multiple sheets, formulas, formatting).
    • Generating PDF reports, checklists, or forms.
    • Data transformations using pandas.
    • Operations that might exceed agent step limits.

    When NOT to use:

    • Simple single-cell reads/writes.
    • Tasks requiring interactive user input.
    • Tasks where the agent needs to iteratively refine the approach.

  6. OpenSpace v2 Key Features

    main

    OpenSpace v2 introduces several major improvements focused on quality and usability:

    • Package-based Skill Browsing: Browse skills organized into packages.
    • Skill Quality Summaries: View usage-quality summaries in package and skill detail views.
    • Task-trace Evidence: Upload task-trace as evidence to validate skill quality (supports idempotent uploads).
    • Enhanced Search: Package-level skill searching and improved discovery.
    • Local Experience: Updated local dashboard, TUI (Terminal User Interface), and runtime services.
    • Improved Connectivity: Stable cloud paths for public browsing and private skill access, including SSE and streamable HTTP for MCP (Model Context Protocol) integration.

  7. Use the pdf-download-extract-fallback skill

    main

    The pdf-download-extract-fallback skill provides a robust workflow for acquiring PDF documents from web sources or processing local files, with progressive fallback strategies to handle failures like JavaScript redirects, corrupted files, or missing tools.

    Scenarios

    • Mode A (Web URL): Use when downloading documents from a URL. It uses curl with a browser user-agent to bypass blocks.
    • Mode B (Local File): Use when the PDF is already on disk. It skips the download step and proceeds directly to validation.

    Extraction Fallback Strategy

    1. Primary: Attempt extraction using pdftotext (part of poppler-utils).
    2. Secondary: If pdftotext fails, fallback to Python's PyMuPDF (imported as fitz).
    3. Tertiary: If all extraction fails, degrade gracefully by documenting the failure and supplementing with domain knowledge.
    name: pdf-download-extract-fallback
description: Multi-step PDF download and text extraction with progressive fallback strategies

  8. OpenSpace MCP Tools and Host Skills Overview

    main

    OpenSpace provides a set of MCP tools that are triggered by two primary host skills. These skills teach the agent when and how to use the underlying tools.

    MCP Tools

    • cloud_auth_flow: Register/login and provision cloud agent keys.
    • execute_task: Multi-step grounding agent loop.
    • search_skills: Local skill search.
    • cloud_browse_skills: LLM-guided cloud package/skill browsing and local taxonomy import.
    • fix_skill: Run a manual FIX job through evolution.
    • upload_skill: Resolve placement and push skill to cloud community.

    Host Skills Mapping

    SkillMCP ToolsPurpose
    skill-discoverycloud_auth_flow, search_skills, cloud_browse_skillsSearch local skills, browse cloud packages step by step when needed $\rightarrow$ decide: follow it yourself, delegate, or skip
    delegate-taskcloud_auth_flow, execute_task, search_skills, cloud_browse_skills, fix_skill, upload_skillSet up cloud access, delegate tasks, use local or LLM-guided cloud skill discovery, run skill repair jobs, upload evolved skills

    Skill Evolution: Skills auto-evolve inside execute_task with statuses: FIX, DERIVED, or CAPTURED. Note that fix_skill is only considered complete when it returns fixed; statuses like accepted_audit_only, rejected, and failed are not uploadable repairs.

  9. Understand the OpenSpace v2 Framework Layers

    main

    OpenSpace v2 is organized into four interconnected layers designed to manage AI Agent skills with a focus on quality and controlled evolution:

    1. Skill Quality Layer: Determines which skills are trustworthy by recording skill outcomes (selection, application, completion, or fallback), tracking tool reliability (failures and latency), and using real task behavior as evidence.
    2. Controlled Skill Evolution Layer: Manages how skills are modified using three primary triggers:
      • FIX: Repairing broken or outdated skills.
      • DERIVED: Creating better or specialized versions from existing skills.
      • CAPTURED: Saving new reusable workflows from successful tasks.
      • Skills transition from provisional to trusted based on successful independent usage, and can be downgraded due to attributable failures. The enabled flag independently controls whether a skill is available for reuse.
    3. Local-First Skill Hub Layer: Facilitates sharing and review. Agents run and reuse skills in a local skill folder. Cloud skills are organized into packages and must be explicitly imported into the local folder before reuse. The hub provides a reviewable history including package info, visibility, evolution history, and quality signals.
    4. Agent Harness Layer: Provides the execution environment that generates quality evidence. It includes recoverable sessions (task history, tool results, file changes), permission-aware tools (sandboxing and validation), and a shared runtime used across CLI, Python API, MCP, gateway, and dashboard.

  10. Extract text from DOCX files using the docx-dual-parse skill

    main

    The docx-dual-parse skill extracts text from Microsoft Word (.docx) files. It is designed to be environment-aware, automatically selecting between a shell-based method (using unzip and sed) and a Python-based method (using the zipfile module) depending on what is available in the current environment (e.g., containers, sandboxes, or minimal images).

    When to use this skill:

    • When you need reliable text extraction in varying environments.
    • When python-docx is unavailable but standard library access exists.
    • When you want an automatic fallback mechanism between shell and Python methods.

  11. Use the spreadsheet-validated-exec skill

    main

    The spreadsheet-validated-exec skill is designed for executing Python scripts for spreadsheet operations (using libraries like pandas or openpyxl) while enforcing a mandatory data validation phase. This prevents wasted iterations by ensuring data sources (local files or remote URLs) are accessible and non-empty before processing begins.

    Use this skill when:

    • Reading/writing complex Excel files with multiple sheets.
    • Data sources require accessibility checks.
    • You need to apply formulas, formatting, or complex transformations.
    • The operation involves multiple steps that might exceed standard agent step limits.
    • You want to avoid shell parsing issues by writing scripts to .py files first.

  12. OpenSpace Dashboard Features Overview

    main

    The OpenSpace dashboard provides several views for managing and inspecting agent skills and workflows:

    • Dashboard: Displays overall health, pipeline stages, top skills, and recent workflows.
    • Skills: A searchable list of skills with score breakdowns.
    • Skill Detail: Provides source previews, lineage graphs, scoring metrics, and recent analyses.
    • Workflows: Accesses recorded workflow sessions from logs/recordings and logs/trajectories.
    • Workflow Detail: Shows timelines, artifacts, metadata, selected skills, plans, and decisions.