langcode_agent/docs/skills-management-design.md

Skill Management Design for LangCode Agent

Overview

The Skill Management feature enables LangCode Agent to discover, install, uninstall, and manage agent skills from skill registries like skills.sh. This functionality allows users to extend the agent's capabilities by leveraging community-developed skills that encapsulate domain expertise, specialized tools, and reusable workflows.

Architecture

The skill management system consists of three main components:

1. Skill Manager (skill_manager.py):

   • Handles all interactions with skill registries (primarily skills.sh CLI)
   • Provides functions for searching, installing, uninstalling, listing, and getting details about skills
   • Includes fallback mechanisms when the skills.sh CLI is not available
   • Manages the local skills directory (~/.langcode/skills/)

2. Skill Tools (main.py):

   • Converts skill management functions into LangChain Tool objects
   • Makes skill management capabilities available to the LLM agent
   • Includes tools for: search_skills, install_skill, uninstall_skill, list_installed_skills, get_skill_details

3. CLI Integration (main.py and config_cli.py):

   • Adds /skills subcommand to the main LangCode CLI
   • Provides direct access to skill management functions via terminal commands
   • Integrates with the existing configuration and command processing systems

CLI Usage

The skill management functionality is accessible through the /skills subcommand:

langcode skills search <query> [--limit <n>]
langcode skills install <skill_name> [--version <version>]
langcode skills uninstall <skill_name>
langcode skills list
langcode skills details <skill_name>

Command Details

Search for Skills

langcode skills search "web scraping" --limit 5

Searches for skills matching the query and displays results with name, description, version, and author information.

Install a Skill

langcode skills install brave-search

Installs the specified skill from the skill registry. Optionally specify a version with --version.

Uninstall a Skill

langcode skills uninstall brave-search

Removes the specified skill from the local skills installation.

List Installed Skills

langcode skills list

Displays all currently installed skills with their names, descriptions, versions, authors, and installation paths.

Get Skill Details

langcode skills details brave-search

Shows detailed information about a specific skill including description, version, author, category, repository, and homepage.

Natural Language Usage

Once the LangCode Agent is running, users can interact with skill management features using natural language:

Examples:

• "Search for skills related to web scraping"
• "Install the brave-search skill"
• "What skills do I have installed?"
• "Show me details about the mcp-builder skill"
• "Uninstall the github-api skill"

The agent will use its skill management tools to perform these operations and provide feedback on the results.

Skill Management Tools Available to the Agent

When the agent initializes with skill management enabled, it gains access to these LangChain Tools:

1. search_skills: Search for agent skills in the skills.sh registry

   • Input: query (string), limit (integer, optional, default 10)
   • Output: Formatted list of matching skills with details

2. install_skill: Install a skill from the skills.sh registry

   • Input: skill_name (string)
   • Output: Success or error message

3. uninstall_skill: Uninstall an installed skill

   • Input: skill_name (string)
   • Output: Success or error message

4. list_installed_skills: List all currently installed skills

   • Input: None
   • Output: Formatted list of installed skills with details

5. get_skill_details: Get detailed information about a specific skill

   • Input: skill_name (string)
   • Output: Detailed skill information

Workflow Examples

Discovering and Installing a New Skill

1. User: "Search for skills about GitHub integration"
2. Agent: Uses search_skills tool to find relevant skills
3. Agent: Returns list of GitHub-related skills (e.g., github-api, github-actions)
4. User: "Install the github-api skill"
5. Agent: Uses install_skill tool to install the skill
6. Agent: Confirms successful installation
7. User: Now the agent can use GitHub API tools through the newly installed skill

Managing Existing Skills

1. User: "What skills do I have installed?"
2. Agent: Uses list_installed_skills tool to show current skills
3. User: "Show me details about the brave-search skill"
4. Agent: Uses get_skill_details tool to display comprehensive information
5. User: "Uninstall the brave-search skill"
6. Agent: Uses uninstall_skill tool to remove the skill
7. Agent: Confirms successful removal

Technical Implementation Details

Skill Manager Class

The SkillManager class in skill_manager.py provides the core functionality:

• search_skills(query, limit): Uses skills search CLI command with JSON output
• get_skill_details(skill_name): Uses skills show CLI command with JSON output
• install_skill(skill_name, version): Uses skills add CLI command
• uninstall_skill(skill_name): Uses skills rm CLI command
• list_installed_skills(): Uses skills list CLI command
• skill_is_installed(skill_name): Checks if a skill is in the installed list
• get_skill_path(skill_name): Returns filesystem path to installed skill

Fallback Mechanisms

When the skills.sh CLI is not available:

• Search functions return empty results
• Installation/uninstallation functions return error messages
• Local skills directory checking provides basic installed skill information

Integration with Agent System

• Skill tools are added to the agent's toolset in get_custom_tools() alongside MCP, Proxmox, and provider tools
• The agent's system prompt is updated to inform users about skill management capabilities
• CLI commands are integrated into the main command processing flow in process_command()

Configuration

Skill management uses the local skills directory by default:

• Location: ~/.langcode/skills/
• Automatically created when first needed
• Each skill is installed in its own subdirectory
• Skills consist of a SKILL.md file and any supporting files/scripts

No additional configuration is required to use skill management - it works out of the box with the skills.sh CLI when available.

Dependencies

The skill management feature requires:

1. skills.sh CLI (primary method): For full functionality including search, install, uninstall

   • Install via: npm install -g @openai/codex (includes skills.sh)
   • Or follow skills.sh installation instructions

2. Python subprocess module: For executing skills.sh commands

   • Included in standard Python library

When skills.sh is not available:

• Basic functionality is limited to checking locally installed skills
• Search, install, and uninstall operations will return appropriate error messages
• The system gracefully degrades rather than failing completely

Security Considerations

• Skill installation executes code from external sources - users should review skills before installing
• The skill manager does not automatically execute skill code - it only manages installation
• Skills are installed to a local directory under user control
• Users should only install skills from trusted sources
• The system does not grant additional permissions to installed skills beyond what the agent already has

Troubleshooting

"skills.sh command not found"

• Install skills.sh using: npm install -g @openai/codex
• Ensure the npm global bin directory is in your PATH
• Verify installation with: skills --version

Skill installation fails

• Check your internet connection
• Verify the skill name is correct
• Some skills may have specific dependencies or requirements
• Try installing without specifying a version to get the latest compatible version

No skills found in search

• Try different or more general search terms
• Check that skills.sh is properly installed and authenticated
• Some skills may not be publicly available or may require specific access

Skill not found after installation

• Verify installation completed successfully
• Check the local skills directory (~/.langcode/skills/)
• Use /skills list to confirm the skill appears in the installed list
• Restart the agent if necessary to reload available tools

Best Practices

1. Search before installing: Use search to find the most relevant skill for your needs
2. Check skill details: Review description, version, and author before installing
3. Start with popular skills: Well-maintained skills with good documentation are safer choices
4. Keep skills updated: Periodically check for updates to installed skills
5. Remove unused skills: Keep your skills directory clean by uninstalling skills you no longer need
6. Review skill content: For security, examine SKILL.md and supporting files before relying on a skill
7. Combine with MCP: Many skills work best when combined with MCP servers for external service access

Future Enhancements

Potential improvements to the skill management system include:

• Integration with multiple skill registries beyond skills.sh
• Skill version management and upgrading
• Skill dependency resolution
• Skill categorization and tagging systems
• Offline skill distribution and sharing
• Skill validation and safety scanning
• Integration with agent configuration for skill-specific settings
• Web interface for skill management

Example Session

$ langcode
🚀 Initializing LangCode Agent...
✅ Agent initialized successfully!

🔧 Available tools:
  • Provider tools: list models, test connections, set defaults
  • Proxmox tools: manage VMs, snapshots, resources
  • MCP tools: accessing external services and skills registries (like skills.sh)
  • Skill management tools: discovering, installing, and managing agent skills
  • Standard tools: planning, filesystem, shell, subagents

💬 You can now interact with the agent.
📌 Comandi speciali (prefissati con /):
   /help   - Mostra i comandi disponibili
   /status - Mostra lo stato del sistema
   /config - Gestisci le configurazioni
   /skills - Gestione skill agent
   /exit   - Esci dall'agente

💡 Per chattare, scrivi semplicemente il tuo messaggio.

👤 You: Search for skills about web scraping
🤖 LangCode: 
Found 3 skills:
1. brave-search
   Description: Helps you structured brave web search queries and summarizer workflows
   Version: 1.0.0
   Author: skillmd.ai

2. scrape-web
   Description: Skill for scraping web content with various options
   Version: 0.5.0
   Author: webtools.dev

3. html-parser
   Description: Parse and extract data from HTML documents
   Version: 2.1.0
   Author: dataparsers.org

👤 You: Install the brave-search skill
🤖 LangCode: ✅ Skill 'brave-search' installed successfully

👤 You: What skills do I have installed?
🤖 LangCode: 
Installed skills (1):
1. brave-search
   Description: Helps you structured brave web search queries and summarizer workflows
   Version: 1.0.0
   Author: skillmd.ai
   Path: /home/user/.langcode/skills/brave-search

👤 You: Show me details about the brave-search skill
🤖 LangCode: 
Skill Details: brave-search
==================================================
Description: Helps you structured brave web search queries and summarizer workflows
Version: 1.0.0
Author: skillmd.ai
Category: development
Repository: https://github.com/skillmd/brave-search
Homepage: https://skillmd.ai/how-to-build/brave-search-13/

👤 You: Now I want to scrape a website and summarize the content
🤖 LangCode: I can help you with that! First, let me use the brave-search skill to search for information about the website you're interested in. What specific website or topic would you like me to research?

This demonstrates the complete workflow from discovering skills to installing them and using their capabilities through natural language interaction with the LangCode Agent.