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

Skill Framework Migration: Step-by-Step AI Implementation Plan

This document serves as a self-contained, step-by-step guide for an AI agent to execute the migration from the flat, database-backed skill system to the new "Skills as Folders" (Lazy-Loading) architecture.

Prerequisites to check before starting:

  • Backend uses FastAPI (/app/ai-hub/app/api/).
  • Frontend uses React (/app/frontend/src/features/skills/).
  • Database uses SQLAlchemy (/app/db/models.py).

Phase 1: Database & Model Virtualization (Backend)

Objective: Evolve the Skill model to support a Virtual File System (VFS) instead of monolithic text fields.

  • Step 1.1: Create the SkillFile SQLAlchemy Model

    • Location: /app/ai-hub/app/db/models.py
    • Action: Define a new SkillFile model with:
      • id (Integer, Primary Key)
      • skill_id (Integer, Foreign Key to skills.id)
      • file_path (String, e.g., SKILL.md, scripts/run.py, artifacts/data.json)
      • content (Text or LargeBinary, to hold file data)
      • created_at / updated_at (DateTime)
    • Action: Add a files = relationship("SkillFile", back_populates="skill", cascade="all, delete-orphan") to the main Skill model.

  • Step 1.2: Deprecate Legacy Fields in the Skill Model

    • Location: /app/ai-hub/app/db/models.py
    • Action: Mark system_prompt, preview_markdown, and config as nullable/deprecated. The core logic should now expect a SKILL.md file in the SkillFile table to replace system_prompt and preview_markdown.

  • Step 1.3: Generate & Run Alembic Migration

    • Action: Run the command to generate an alembic migration script for the new SkillFile table and apply it to the database.

Phase 2: REST API Overhaul (Backend)

Objective: Expose endpoints for standard IDE operations (CRUD for files/folders).

  • Step 2.1: Implement File Tree API

    • Location: /app/ai-hub/app/api/routes/skills.py
    • Action: Create GET /skills/{skill_id}/files.
    • Logic: Return a hierarchical JSON representation of the files associated with the skill (e.g., simulating folders by parsing the file_path strings).

  • Step 2.2: Implement File Content CRUD Operations

    • Location: /app/ai-hub/app/api/routes/skills.py
    • Action: Create GET /skills/{skill_id}/files/{path:path} to read a specific file's text/binary content.
    • Action: Create POST /skills/{skill_id}/files/{path:path} to create or update file contents.
    • Action: Create DELETE /skills/{skill_id}/files/{path:path} to remove a file.

  • Step 2.3: Modify Skill Creation Logic

    • Location: /app/ai-hub/app/api/routes/skills.py (POST /skills/)
    • Action: Upon creating a new skill, automatically seed the SkillFile database with a default SKILL.md file containing basic boilerplate instructions.

Phase 3: "Lazy Loading" Agent Logic Integration (Backend/Worker)

Objective: Teach the AI agent how to interact with this new folder structure instead of relying on the giant system_prompt.

  • Step 3.1: Create the read_skill_artifact Tool

    • Location: Core agent tooling directory (e.g., /app/ai-hub/app/core/agent/tools.py or similar).
    • Action: Program a standard tool allowing the LLM to provide a skill_name and file_path to read content dynamically during a session.

  • Step 3.2: Update Agent Initialization Context

    • Location: Node/Agent execution wrapper (sessions.py or agent orchestrator).
    • Action: When loading a skill for an agent, inject only the contents of SKILL.md into the initial system prompt. Provide the agent with the read_skill_artifact tool to discover and read anything in the /scripts/ or /artifacts/ folders when necessary.

Phase 4: The "Skill Studio" IDE Upgrade (Frontend)

Objective: Replace the basic textarea forms with a true workspace IDE UI.

  • Step 4.1: Abstract File APIs in Frontend Service

    • Location: /app/frontend/src/services/apiService.js
    • Action: Add helper functions: getSkillFiles(id), getSkillFileContent(id, path), saveSkillFile(id, path, content), deleteSkillFile(id, path).

  • Step 4.2: Build the File Tree Sidebar Component

    • Location: /app/frontend/src/features/skills/components/SkillFileTree.js (New Component)
    • Action: Implement a clickable folder/file tree UI. Selecting a file triggers a state update for the active open code editor.

  • Step 4.3: Implement the Code Editor Component

    • Location: /app/frontend/src/features/skills/components/SkillEditor.js (New Component)
    • Action: Drop in a code editor (like Monaco Editor, or a high-quality textarea with syntax highlighting) to edit the active file fetched in Step 4.2.
    • Action: Add "Save" shortcuts (Ctrl+S) hooked to the saveSkillFile API.

  • Step 4.4: Refactor SkillsPageContent.js

    • Location: /app/frontend/src/features/skills/components/SkillsPageContent.js
    • Action: Remove the legacy "Engineering Mode" and monolithic textareas (formData.system_prompt, formData.preview_markdown, formData.config).
    • Action: Replace the modal body with the newly created Workspace Layout: Side-by-side split view of SkillFileTree (Left) and SkillEditor (Right).

Final Validation Checklist

  1. Create a new skill; verify SKILL.md is automatically created.
  2. Add a new file scripts/test.py via the Frontend UI.
  3. Observe the AI Agent reading SKILL.md by default, but executing a tool to read scripts/test.py only when requested.
  4. Verify token counts drop significantly compared to the legacy monolithic system prompt.