Fork: 0
yangyangxie / cortex-hub
Transfer to URL with SHA Find file
Newer
Older
cortex-hub / docs / features / skills_page.md
@Antigravity AI Antigravity AI 11 hours ago 4 KB feat/fix: Rich token usage popovers, robust LiteLLM context window bounds logic, and Skill management refactor
Raw Blame History

Cortex Skills Feature Architecture

Overview

The "Cortex Skills" feature serves as the central orchestration and management interface for AI capabilities within the Cortex Hub ecosystem. It provides a robust full-stack solution for viewing, creating, sharing, and managing modular AI skills (native, MCP, or gRPC protocols).

Frontend Architecture

Located primarily in /app/frontend/src/features/skills, the frontend follows a clean Container/Presenter pattern to separate state management from UI rendering.

Components

  1. SkillsPage (Container)

    • Location: /app/frontend/src/features/skills/pages/SkillsPage.js
    • Manages state, data fetching (CRUD operations using apiService), and filtering logic.
    • Holds complex states such as advanced "Engineering Mode" toggles, modal visibility, and contextual payload editing.

  2. SkillsPageContent (Presenter)

    • Location: /app/frontend/src/features/skills/components/SkillsPageContent.js
    • Renders the UI and consumes state via a shared context property.
    • Designed with modern UI paradigms: dynamic grids, blurring (backdrop-blur), visual cues, micro-animations, and a responsive sidebar.

Frontend Features

  • Sidebar & Filtering System: Four distinct visual filters:
    • All Libraries: Every skill available to the user.
    • System Core: Built-in immutable skills.
    • My Creations: Skills created and owned by the logged-in user.
    • Shared Works: Skills inherited via group policy.
  • Universal Search & System Toggling: Fast text-based searching (checking names and descriptions) paired with a toggle to hide system skills to reduce visual noise.
  • Skill Grid: Visually distinct skill cards utilizing extra_metadata.emoji for quick identification. Displays disabled skills with an opacity-60 grayscale filter.
  • Docs Viewer Modal: Integrated ReactMarkdown rendering for preview_markdown, allowing users to see public instructions vs the raw "Intelligence Blueprint".
  • Engineering Mode (Editor Modal): Contains both basic fields (Name, Emoji, Manifesto, Protocol Type) and advanced configuration states (Intelligence Protocol System Prompt, Network Config JSON validator, Markdown definitions).

Backend Architecture

The backend REST API is built in FastAPI under /app/ai-hub/app/api/routes/skills.py. It is responsible for advanced access control, system-level safety, and complex querying.

Endpoints

  • GET /skills/: Lists skills, enforcing multi-level Access Control Logic (ACL).
  • POST /skills/: Creates a given skill configuration.
  • PUT /skills/{skill_id}: Overwrites skill configurations.
  • DELETE /skills/{skill_id}: Purges a skill from the ecosystem.

Access Control & Policy Logic

  1. System Protection:
    • is_system skills are immutable. They cannot be modified or deleted via the API, not even by administrators. This protects the core platform loops.
    • Only admins can create new is_system skills.
  2. Read/Visibility Rules:
    • Administrators: Complete visibility of all skills, regardless of is_enabled status or ownership.
    • Normal Users: View system skills (if enabled), their own skills (where owner_id == user.id and enabled), and Group Skills. Group skills are dynamically matched by checking current_user.group.policy.get("skills", []).
  3. Filtering:
    • The API supports a feature query parameter (e.g., ?feature=swarm_control or ?feature=voice), filtering the query arrays to only return relevant capabilities for specific frontend sub-systems.
  4. Validations:
    • Automatic uniqueness checks for the name field on creation and modification.
    • Strict owner-only (or admin) checks injected into PUT and DELETE policies to prevent arbitrary modification.

Data Model Structure (Key Fields)

  • name (String): Unique string identifier (e.g. browser_eval).
  • skill_type (String): Network protocol format - Native (local), MCP (mcp), or remote (remote_grpc).
  • config (JSON): Configuration network JSON payload.
  • system_prompt (String): Internal LLM instructions invisible to end-users unless explicitly provided.
  • features (Array): Target application bindings mapping where the skill should be active (e.g., ['swarm_control', 'voice_chat', 'workflow']).
  • is_system & is_enabled (Boolean): Core booleans managing lifecycle state and system protection.
  • extra_metadata (JSON): Contains UI metadata and arbitrary frontend parameters (e.g., UI emoji).
  • preview_markdown (String): The operational documentation presented to the user.