DeepSeek TUI Skill Loading Execution System: Architecture and Implementation

DeepSeek TUI implements a unified load_skill tool that discovers, validates, and loads self-contained skill definitions—including companion files—in a single operation, eliminating the need for multiple file system calls.

DeepSeek TUI provides a dedicated mechanism for dynamically loading skills into the conversation context through a specialized tool call. This skill loading execution system, implemented in the Rust-based terminal UI, allows the language model to fetch complete skill definitions from multiple discovery sources in one atomic operation.

Skill Discovery Architecture

The discovery layer walks a prioritized set of candidate directories to build a name-to-skill mapping. According to the source code in crates/tui/src/skills.rs, the system searches workspace-local paths (.agents/skills, ./skills, .opencode/skills) and the global user directory (~/.deepseek/skills).

When a conversation turn begins, the system prompt already lists all available skills using the same registry. This guarantees that load_skill can only request names that exist in the pre-computed discovery set.

Building the Skill Registry

The discover_in_workspace function constructs the registry by scanning these directories and mapping skill names to their metadata. This registry persists for the duration of the tool context, ensuring consistent availability across turns.

The load_skill Tool API

The tool API exposes load_skill to the LLM through a strict JSON schema defined in crates/tui/src/tools/skill.rs. The ToolSpec::input_schema validates a single required field: name.

Input Validation

The schema ensures the model provides exactly one parameter—the skill name—which the system then resolves against the pre-built registry. If the name is missing or empty, the tool returns a clear ToolError with hints listing valid skill names.

Skill Loading Execution Flow

The LoadSkillTool::execute method in skill.rs orchestrates three distinct phases: resolution, formatting, and metadata packaging.

Skill Resolution and Error Handling

Lines 87-94 in skill.rs perform the registry lookup:

let registry = discover_in_workspace(&context.workspace);
let Some(skill) = registry.get(name) else { … };

If resolution fails, lines 95-113 generate a helpful error message containing available skill names, allowing the model to recover without guessing.

Body Formatting and Companion Files

The format_skill_body function (lines 28-55) constructs a self-contained markdown payload containing:

• A header with the skill name
• Optional description
• Source path
• Raw SKILL.md content
• A "Companion files" section (when applicable)

The collect_companion_files function (lines 61-82) reads the skill's directory, filters out directories and the SKILL.md file itself, and sorts remaining files for deterministic output.

Result Metadata Structure

The tool returns a ToolResult containing:

• content: The formatted markdown body
• metadata: A structured object with three keys:
  • skill_name: The canonical skill identifier
  • skill_path: Absolute path to the SKILL.md file
  • companion_files: Array of sibling file paths

Practical Usage Examples

Programmatic Invocation

To load a skill programmatically within the DeepSeek TUI engine:

// Build a tool context pointing at the workspace.
let mut ctx = ToolContext::new(workspace_path);

// Call the tool from the engine (async).
let result = LoadSkillTool
    .execute(json!({ "name": "review-pr" }), &ctx)
    .await?;

// `result.content` is a markdown block the model can read directly.
println!("{}", result.content);

// The companion files are available for later `read_file` calls.
let companion_paths = result.metadata.unwrap()["companion_files"]
    .as_array().unwrap()
    .iter()
    .map(|v| v.as_str().unwrap())
    .collect::<Vec<_>>();

TUI Command Interface

Users invoke the tool directly in the chat composer:

1. Type /load_skill name=review-pr and press Enter.
2. The TUI renders the skill's markdown body (header, description, and instructions) in the conversation transcript.
3. If the skill includes helper scripts, the model can subsequently call read_file on any path listed in the companion files array.

Summary

• Discovery scans multiple sources: The system checks workspace-local and global directories to build a complete skill registry.
• Single-call loading: The load_skill tool fetches the entire skill definition—including SKILL.md and companion files—in one operation.
• Strict validation: Input schema validates the name parameter, and execution provides clear error hints when skills are missing.
• Self-contained output: The formatted body includes all necessary context, while metadata exposes paths for subsequent file operations.
• Deterministic behavior: Companion files are sorted alphabetically to ensure consistent output across sessions.

Frequently Asked Questions

What directories does DeepSeek TUI search for skills?

The discovery system searches four locations in order: workspace-local .agents/skills, ./skills, .opencode/skills, and the global ~/.deepseek/skills directory. This multi-source approach allows both project-specific and user-wide skill definitions.

How does the error handling work when a skill name is invalid?

When the requested skill name cannot be found in the registry, the tool returns a ToolError containing a formatted hint. This hint either indicates that no skills are available or lists the valid skill names discovered in the workspace, enabling the model to correct its request without trial and error.

What information is included in the tool's metadata response?

The load_skill tool returns three metadata keys: skill_name (the canonical identifier), skill_path (absolute filesystem path to the SKILL.md file), and companion_files (an array of paths to sibling files in the skill directory, excluding SKILL.md itself).

Can the model access files referenced by a loaded skill?

Yes. After loading a skill, the model receives a list of companion file paths in the metadata. The model can then invoke read_file on any of these paths to access helper scripts, configuration files, or other assets included with the skill.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}