Skills System
Relevant source files
The following files were used as context for generating this wiki page:
The Skills System in QQcode is a framework designed to extend the assistant's capabilities by loading domain-specific expertise, specialized workflows, and best practices on demand. Skills allow the agent to adapt to specific technical environments or tasks—such as frontend design or data analysis—by injecting targeted instructions and context into the conversation when requested. Sources: README.md:143-145, vibe/core/tools/builtins/prompts/skill.md:12-14
Architecturally, the system relies on a discovery mechanism that scans specific local and global directories for SKILL.md files. These files contain YAML frontmatter defining the skill's metadata and Markdown content providing the detailed guidance the LLM follows once the skill is activated. Sources: vibe/core/skills/manager.py:44-48, vibe/core/tools/builtins/skill.py:73-77
Architecture and Components
The Skills System consists of a manager for discovery, a dedicated tool for activation, and a standardized file structure for definition.
SkillManager
The SkillManager is the central component responsible for identifying available skills and reading their content. It computes search paths across the project and global configuration directories, parses frontmatter to extract metadata, and generates prompt sections for the LLM. Sources: vibe/core/skills/manager.py:44-55
The diagram above illustrates the structure of the SkillManager and its relationship with the SkillInfo data model.
Sources: vibe/core/skills/manager.py:27-36, vibe/core/skills/manager.py:44-55
Skill Discovery Logic
Discovery follows a strict priority order where project-local skills override global ones. The manager iterates through subdirectories in designated paths looking for SKILL.md files. Sources: vibe/core/skills/manager.py:61-65, vibe/core/skills/manager.py:112-115
| Search Priority | Location | Description |
|---|---|---|
| 1 (High) | ./.qqcode/skills/ | Project-specific skills located in the working directory. |
| 2 (Low) | ~/.qqcode/skills/ | Global skills available across all projects. |
Sources: vibe/core/skills/manager.py:66-78, README.md:147-150
Skill Definition Format
Each skill is defined by a directory containing a SKILL.md file. The system uses a specific regex pattern to extract YAML frontmatter. Sources: vibe/core/skills/manager.py:17-21, tests/skills/test_skill_manager.py:27-38
---
name: frontend-design
description: Guidelines for creating modern UIs.
---
# Instructions
Follow these steps to build the UI...
Sources: vibe/core/skills/manager.py:112-115, vibe/core/tools/builtins/prompts/skill.md:1-10
Skill Tool and LLM Interaction
The Skill tool (implemented in vibe/core/tools/builtins/skill.py) serves as the bridge between the LLM and the Skills System. It allows the agent to explicitly "activate" a skill when it recognizes a task matching a skill's description. Sources: vibe/core/tools/builtins/skill.py:65-71
Tool Execution Flow
When the LLM calls the skill tool, the system retrieves the file content and returns it as a tool result, which effectively updates the LLM's context with the new instructions. Sources: vibe/core/tools/builtins/skill.py:86-104
Sequence of events during skill activation.
Sources: vibe/core/tools/builtins/skill.py:86-106, vibe/core/skills/manager.py:165-175
Integration with System Prompt
The system automatically informs the LLM of available skills via the get_skills_prompt_section method. This creates an XML-formatted list of skill names and descriptions within the system prompt. Sources: vibe/core/skills/manager.py:192-205, vibe/core/system_prompt.py:318-322
<available_skills>
- name: frontend-design
description: Guidelines for creating modern UIs.
</available_skills>
Sources: vibe/core/skills/manager.py:202-208
Data Models and Exceptions
The system utilizes Pydantic models for structured data handling and specific exception classes for error states.
Core Data Models
| Model | Purpose | Key Fields |
|---|---|---|
SkillInfo | Metadata for a discovered skill. | name, description, path |
SkillArgs | Input for the skill tool. | name |
SkillResult | Output from tool execution. | skill_name, content, skill_path, success |
Sources: vibe/core/skills/manager.py:27-36, vibe/core/tools/builtins/skill.py:30-33, vibe/core/tools/builtins/skill.py:36-43
Error Handling
The system defines a custom SkillNotFoundError which is raised by the SkillManager if a requested name does not exist. This error is caught by the Skill tool and converted into a ToolError for the LLM to process. Sources: vibe/core/skills/manager.py:39-50, vibe/core/tools/builtins/skill.py:105-108
Usage Guidelines for the Agent
The skill.md prompt file provides the agent with specific heuristics for using the system:
- Proactive Activation: The agent should check the
<available_skills>section and activate a skill if the user's request matches a description. Sources: vibe/core/tools/builtins/prompts/skill.md:12-14 - Directory Awareness: Skills can reference other files (scripts, templates) within their specific subdirectory. Sources: vibe/core/tools/builtins/prompts/skill.md:21-25
- Workflow Adherence: Once activated, the agent must follow the instructions within the skill content for the remainder of the task. Sources: vibe/core/tools/builtins/prompts/skill.md:16-19
The Skills System provides a modular way to manage complex, domain-specific logic without bloating the primary system prompt, ensuring the assistant remains efficient while gaining specialized knowledge only when necessary. Sources: README.md:143-145, vibe/core/system_prompt.py:318-322