# Skills System Loading Flow Diagram ## Overview ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ SKILL LOADING FLOW │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ## Phase 1: Discovery (Progressive Disclosure Tier 0-1) ``` ┌─────────────┐ ┌─────────────────────┐ ┌─────────────────────────────┐ │ User │────▶│ skills_categories() │────▶│ Returns: │ │ Request │ │ (Tier 0) │ │ - category names │ └─────────────┘ └─────────────────────┘ │ - descriptions │ │ - skill counts │ └─────────────────────────────┘ │ ▼ ┌─────────────────────────────┐ │ skills_list(category=...) │ │ (Tier 1) │ └─────────────────────────────┘ │ ▼ ┌─────────────────────────────┐ │ Returns: │ │ - name (≤64 chars) │ │ - description (≤1024) │ │ - category │ └─────────────────────────────┘ ``` ## Phase 2: Resolution ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ SKILL RESOLUTION │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────────────────────────┐ │ │ │ Search Order (First Match Wins) │ │ │ └─────────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────┼──────────────────────────┐ │ │ ▼ ▼ ▼ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ 1. Direct │ │ 2. Name │ │ 3. Legacy │ │ │ │ Path │ │ Match │ │ Flat MD │ │ │ ├────────────┤ ├────────────┤ ├────────────┤ │ │ │ mlops/ │ │ Search all │ │ {name}.md │ │ │ │ axolotl/ │ │ SKILL.md │ │ files │ │ │ │ SKILL.md │ │ for name │ │ │ │ │ └────────────┘ └────────────┘ └────────────┘ │ │ │ │ Search Directories (in order): │ │ 1. ~/.hermes/skills/ (local) │ │ 2. External dirs from config.yaml │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` ## Phase 3: Security & Validation ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ SECURITY PIPELINE │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────┐ │ skill_view() │ │ Invocation │ └────────┬────────┘ │ ┌────────────────┼────────────────┐ ▼ ▼ ▼ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ Platform │ │ Injection │ │ Path │ │ Check │ │ Scan │ │ Traversal │ ├────────────┤ ├────────────┤ ├────────────┤ │ platforms: │ │ Patterns: │ │ ".." │ │ [macos] │ │ - ignore │ │ blocks │ │ │ │ prev │ │ escape │ │ Skip if │ │ - system │ │ attempts │ │ mismatch │ │ prompt │ │ │ └────────────┘ └────────────┘ └────────────┘ │ │ │ └────────────────┼────────────────┘ ▼ ┌─────────────────┐ │ Trust Check │ ├─────────────────┤ │ Is skill from │ │ trusted dirs? │ │ (local + config)│ └─────────────────┘ ``` ## Phase 4: Content Loading ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ CONTENT ASSEMBLY │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────┐ │ Parse SKILL.md │ │ (Frontmatter) │ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ Extract Metadata │ │ ├─ name │ │ ├─ description │ │ ├─ version │ │ ├─ platforms │ │ ├─ prerequisites │ │ ├─ metadata.hermes │ │ │ ├─ tags │ │ │ └─ related_... │ │ └─ setup │ └──────────┬──────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ LINKED FILES DISCOVERY │ └─────────────────────────────────────────────────────────────────────────┘ │ ┌───────┼───────┐ ▼ ▼ ▼ ┌────────┐┌────────┐┌────────┐ │references/│templates/│ scripts/│ ├────────┤├────────┤├────────┤ │ *.md ││ *.md ││ *.py │ │ docs ││ *.py ││ *.sh │ │ specs ││ *.yaml ││ helpers│ └────────┘└────────┘└────────┘ │ │ │ └───────┼───────┘ ▼ ┌─────────────────────┐ │ Return JSON: │ │ { │ │ name, │ │ description, │ │ content, │ │ linked_files, │ │ tags, │ │ related_skills, │ │ setup_needed, │ │ ... │ │ } │ └─────────────────────┘ ``` ## Phase 5: Prerequisites & Setup ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ PREREQUISITES RESOLUTION │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │ Required Environment Variables │ └─────────────────────────────────────────────────────────────────────────┘ │ ┌───────────────────────┼───────────────────────┐ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Check Env │ │ Gateway │ │ Local │ │ Exists? │ │ Surface │ │ CLI │ └──────┬──────┘ └─────────────┘ └─────────────┘ │ (Hint only) (Interactive │ secret capture) ┌─────┴─────┐ ▼ ▼ ┌────────┐ ┌────────┐ │ Yes │ │ No │ └───┬────┘ └───┬────┘ │ │ ▼ ▼ ┌────────┐ ┌───────────────────────────────────────────────────────────┐ │Register│ │ Secret Capture Flow │ │for │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │passthrough│ │ │ Prompt │───▶│ User Input │───▶│ Validate │ │ └────────┘ │ │ │ User │ │ │ │ & Store │ │ │ │ └─────────────┘ └─────────────┘ └──────┬──────┘ │ │ │ │ │ │ │ ┌────────────────────────────────────────────┘ │ │ │ ▼ │ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ │ Success │ │ Skipped │ │ │ │ │ Continue │ │ Mark setup│ │ │ │ │ │ │ as needed │ │ │ │ └─────────────┘ └─────────────┘ │ │ └───────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Required Credential Files │ └─────────────────────────────────────────────────────────────────────────┘ │ ┌──────────────┴──────────────┐ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ Exists │ │ Missing │ │ Register │ │ Mark │ │ for mount │ │ setup │ │ to remote │ │ needed │ └─────────────┘ └─────────────┘ ``` ## Phase 6: Registry Integration ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ TOOL REGISTRY INTEGRATION │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │ tools/skills_tool.py │ └─────────────────────────────────────────────────────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ skills_list │ │ skill_view │ │ skill_manage│ │ Schema │ │ Schema │ │ Schema │ ├─────────────┤ ├─────────────┤ ├─────────────┤ │ category │ │ name │ │ action │ │ (optional) │ │ file_path │ │ name │ │ │ │ (optional) │ │ content │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ └───────────────┼───────────────┘ ▼ ┌─────────────────────────────┐ │ tools/registry.py │ │ ┌─────────────────────┐ │ │ │ registry.register() │ │ │ │ - name │ │ │ │ - toolset="skills" │ │ │ │ - schema │ │ │ │ - handler │ │ │ │ - check_fn │ │ │ │ - emoji="📚" │ │ │ └─────────────────────┘ │ └─────────────────────────────┘ │ ▼ ┌─────────────────────────────┐ │ Model Context │ │ (Available to LLM) │ └─────────────────────────────┘ ``` ## Slash Command Flow ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ SLASH COMMAND INVOCATION │ └─────────────────────────────────────────────────────────────────────────────────┘ User types: "/axolotl fine-tune llama-3" │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ agent/skill_commands.py │ │ scan_skill_commands() │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ 1. Scan all skills directories │ │ 2. Build map: /skill-name -> skill_info │ │ 3. Match: /axolotl found │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ build_skill_invocation_message() │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Construct message: │ │ │ │ [SYSTEM: User invoked "axolotl" skill...] │ │ │ │ {SKILL.md content} │ │ │ │ [Supporting files available...] │ │ │ │ The user provided: "fine-tune llama-3" │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Add to conversation context │ │ (System or User message) │ └─────────────────────────────────────────────────────────────────────────┘ ``` ## Installation Sources Flow ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ SKILL INSTALLATION SOURCES │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ BUILT-IN SKILLS │ │ (Trust: builtin) │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Repository Setup Command Status │ │ ───────────────────────────────────────────────────────────────────── │ │ skills/ ./setup-hermes.sh Active │ │ (bundled) → copies to ~/.hermes/skills/ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OPTIONAL SKILLS │ │ (Trust: builtin) │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ optional-skills/ hermes skills install On-demand │ │ (bundled, inactive) → copies to ~/.hermes/skills/ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ SKILLS HUB │ │ (Trust: varies by source) │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │ │ openai/ │ │ anthropic/ │ │ community/ │ │ │ │ skills │ │ skills │ │ repos │ │ │ ├───────────────┤ ├───────────────┤ ├───────────────┤ │ │ │ Trust: │ │ Trust: │ │ Trust: │ │ │ │ trusted │ │ trusted │ │ community │ │ │ │ │ │ │ │ │ │ │ │ Policy: │ │ Policy: │ │ Policy: │ │ │ │ Caution OK │ │ Caution OK │ │ Block on │ │ │ │ │ │ │ │ any finding │ │ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │ │ │ Flow: │ │ 1. hermes skills search │ │ 2. hermes skills install │ │ 3. Download to quarantine │ │ 4. Security scan │ │ 5. If passed → install to ~/.hermes/skills/.hub/ │ │ 6. Record provenance in lock.json │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────┐ │ EXTERNAL DIRECTORIES │ │ (Trust: user-configured) │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Config: ~/.hermes/config.yaml │ │ ───────────────────────────── │ │ skills: │ │ external_dirs: │ │ - ~/my-custom-skills │ │ - /shared/team-skills │ │ - ${WORKSPACE}/.skills │ │ │ │ Resolution: Local skills take precedence over external │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ## Complete End-to-End Flow ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ COMPLETE SKILL LOADING SEQUENCE │ └─────────────────────────────────────────────────────────────────────────────────┘ 1. USER INPUT │ ├── /command ─────────────────────────────────────────┐ │ ▼ │ ┌─────────────────────┐ │ │ Skill Commands │ │ │ Resolution │ │ └─────────────────────┘ │ │ └── skills_list() ─────────────────────────────────────┤ │ │ ▼ ▼ ┌─────────────────────┐ ┌─────────────────────┐ │ Category Filter? │ │ Load Full Skill │ │ (Tier 0/1) │ │ Content │ └─────────────────────┘ └─────────────────────┘ │ │ ▼ ▼ ┌─────────────────────┐ ┌─────────────────────┐ │ Return Metadata │ │ Security Pipeline │ │ (name, desc) │ │ - Platform check │ └─────────────────────┘ │ - Injection scan │ │ - Path validation │ └─────────────────────┘ │ ▼ ┌─────────────────────┐ │ Parse Frontmatter │ │ Extract metadata │ └─────────────────────┘ │ ▼ ┌─────────────────────┐ │ Resolve Prerequisites│ │ - Env vars │ │ - Credential files │ │ - Commands │ └─────────────────────┘ │ ▼ ┌─────────────────────┐ │ Discover Linked │ │ Files │ │ - references/ │ │ - templates/ │ │ - scripts/ │ │ - assets/ │ └─────────────────────┘ │ ▼ ┌─────────────────────┐ │ Assemble Response │ │ JSON with: │ │ - content │ │ - linked_files │ │ - setup status │ │ - tags, etc │ └─────────────────────┘ │ ▼ ┌─────────────────────┐ │ Add to Context │ │ (LLM can now use │ │ skill knowledge) │ └─────────────────────┘ ``` --- ## Error Handling Flow ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ ERROR HANDLING │ └─────────────────────────────────────────────────────────────────────────────────┘ ┌───────────────────────────────────────────────────────────────────────────────┐ │ Error Type │ Response │ ├───────────────────────────────────────────────────────────────────────────────┤ │ Skill not found │ Return available skills list (up to 20) │ │ Platform mismatch │ Return UNSUPPORTED readiness status │ │ Injection detected │ Log warning, load with caution │ │ Path traversal attempt │ Block with security error │ │ Setup needed (env vars) │ Return SETUP_NEEDED status + missing list │ │ File not found in skill │ Return available files organized by type │ │ Binary file requested │ Return metadata instead of content │ │ Disabled skill │ Inform user how to enable │ └───────────────────────────────────────────────────────────────────────────────┘ ``` --- *Diagram version: 1.0* *Generated: 2024-03-30*