Module 06: Skills System & Self-Improvement

def skill_command(skill_name: str, args: dict = None) -> str:
    """
    Execute a skill as part of the conversation.
    
    Skills are loaded as USER messages (not system prompt) to preserve caching.
    """
    hub = SkillsHub()
    skill = hub.get_skill(skill_name)
    
    if not skill:
        return f"Skill '{skill_name}' not found. Use /skills search to find available skills."
    
    # Build skill context
    skill_context = f"""
---
SKILL: {skill['name']}

{skill['content']}

---
Context:
{json.dumps(args or {})}
"""
    
    # Return as user message (will be injected into conversation)
    return skill_context

# run_agent.py - Inject skills when needed
def build_context(user_message: str, skills: list = None):
    messages = [
        {"role": "system", "content": system_prompt},
        *conversation_history,
    ]
    
    # Load skills as user message (not system!)
    if skills:
        for skill_name in skills:
            skill_content = skill_command(skill_name)
            messages.append({"role": "user", "content": skill_content})
    
    messages.append({"role": "user", "content": user_message})
    return messages

# agent/auxiliary_client.py - Periodic skill suggestion
def suggest_new_skills(conversation: list):
    """
    Analyze conversation and suggest new skills to create.
    
    Triggers after complex multi-step tasks (5+ tool calls).
    """
    if count_tool_calls(conversation) < 5:
        return None  # Not complex enough
    
    prompt = f"""
    Based on this conversation, could a reusable skill be created?
    
    Look for patterns like:
    - Repeated multi-step workflows
    - Common tasks the user asks about
    - Procedures that could be documented
    
    Conversation excerpt:
    {conversation[-30:]}  # Last 30 turns
    
    If a skill makes sense, suggest:
    1. Skill name (kebab-case)
    2. When to use it
    3. Step-by-step instructions
    4. Common pitfalls
    
    Otherwise say "No skill needed."
    """
    
    suggestion = call_llm(prompt)
    return parse_skill_suggestion(suggestion)

def create_skill_from_suggestion(suggestion: dict):
    """
    Create a new skill directory with SKILL.md.
    
    Asks user for approval before saving.
    """
    name = suggestion['name']
    path = os.path.expanduser(f"~/.hermes/skills/{name}/SKILL.md")
    
    # Create directory
    os.makedirs(os.path.dirname(path), exist_ok=True)
    
    # Write skill content
    with open(path, 'w') as f:
        f.write(suggestion['instructions'])
    
    return {
        'success': True,
        'name': name,
        'path': path,
        'message': f"Skill '{name}' created! You can now use /{name} in conversations."
    }

# hermes_cli/main.py - /skills slash command
@slash_command("skills")
def skills(subcommand: str = None, query: str = None):
    """
    Manage skills.
    
    Usage:
        /skills              # List all available skills
        /skills search <q>   # Search skills by keyword
        /skills inspect <name>  # Show a specific skill
        /skills install <url>   # Install from GitHub
    """
    hub = SkillsHub()
    
    if not subcommand:
        # List all skills
        skills = hub.list_all()
        return format_skills_list(skills)
    
    elif subcommand == 'search':
        # Search by keyword in skill content
        results = []
        for skill in hub.list_all():
            skill_data = hub.get_skill(skill['name'])
            if query.lower() in skill_data['content'].lower():
                results.append(skill)
        
        return format_search_results(results, query)
    
    elif subcommand == 'inspect':
        # Show specific skill
        skill = hub.get_skill(query)
        if not skill:
            return f"Skill '{query}' not found."
        
        return f"# {skill['name']}\n\n{skill['content']}"
    
    elif subcommand == 'install':
        # Install from GitHub URL
        return install_skill_from_github(query)

def install_skill_from_github(url: str) -> str:
    """
    Install a skill from a GitHub repository.
    
    Expected format: https://github.com/user/repo/tree/main/skill-name
    Or: user/repo/skill-name (short form)
    """
    # Parse URL to get repo and skill name
    parsed = parse_github_url(url)
    
    if not parsed:
        return "Invalid GitHub URL format."
    
    # Clone or download the skill directory
    target_path = os.path.expanduser(f"~/.hermes/skills/{parsed['skill_name']}")
    
    if os.path.exists(target_path):
        return f"Skill '{parsed['skill_name']}' already exists. Use /skills update first."
    
    # Download from GitHub
    success = download_skill_from_github(parsed, target_path)
    
    if success:
        return f"Skill '{parsed['skill_name']}' installed! You can now use /{parsed['skill_name']}."
    else:
        return "Failed to install skill. Check the URL and try again."

def update_skill_from_error(skill_name: str, error_context: dict):
    """
    Automatically update a skill when it fails.
    
    This is the "self-improving" part of Hermes.
    """
    hub = SkillsHub()
    skill = hub.get_skill(skill_name)
    
    if not skill:
        return f"Skill '{skill_name}' not found."
    
    prompt = f"""
    This skill failed with an error. Update the instructions to prevent this.
    
    Skill: {skill['name']}
    Current instructions:
    {skill['content']}
    
    Error context:
    - What went wrong: {error_context['error']}
    - Steps taken before failure: {error_context['steps']}
    - Environment state: {error_context['state']}
    
    Update the SKILL.md to:
    1. Add this scenario to "Pitfalls" section
    2. Modify steps if needed
    3. Add verification checks
    
    Return only the updated SKILL.md content.
    """
    
    updated_content = call_llm(prompt)
    
    # Save updated skill
    path = os.path.expanduser(f"~/.hermes/skills/{skill_name}/SKILL.md")
    with open(path, 'w') as f:
        f.write(updated_content)
    
    return f"Skill '{skill_name}' updated to handle this error case."

# User can also manually update skills
@slash_command("skills")
def skills_update(skill_name: str, changes: str):
    """
    Manually update a skill.
    
    Usage: /skills update <name> <changes>
    """
    hub = SkillsHub()
    skill = hub.get_skill(skill_name)
    
    if not skill:
        return f"Skill '{skill_name}' not found."
    
    # Apply changes (simple find-and-replace or full rewrite)
    updated_content = apply_changes(skill['content'], changes)
    
    path = os.path.expanduser(f"~/.hermes/skills/{skill_name}/SKILL.md")
    with open(path, 'w') as f:
        f.write(updated_content)
    
    return f"Skill '{skill_name}' updated."

# BAD: Skills as system prompt (breaks caching)
def build_system_prompt():
    skills = load_all_skills()  # Every skill, every time!
    return f"{CORE_PROMPT}\n\nSkills:\n{skills}"

# GOOD: Load as user message on demand
def build_context(user_message):
    messages = [{"role": "system", "content": CORE_PROMPT}]
    
    if needed_skills:
        for skill in needed_skills:
            content = load_skill(skill)
            messages.append({"role": "user", "content": f"SKILL: {content}"})
    
    messages.append({"role": "user", "content": user_message})

# BAD: Too specific, won't be reused
skill_name = "fix-this-specific-bug-in-project-x"

# GOOD: Generalize the pattern
skill_name = "debug-terminal-tool-errors"

# BAD: Let skills rot as APIs change
def execute_skill(skill):
    # Old code that no longer works
    old_api_call()  # Returns error!

# GOOD: Update skills proactively
def update_broken_skills():
    for skill in list_all_skills():
        if skill_has_deprecated_apis(skill):
            suggest_update(skill)