# 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.
