# DeepSeek TUI Skill Loading Execution System: Architecture and Implementation

> Explore the DeepSeek TUI skill loading execution system. Discover how this unified tool streamlines skill discovery, validation, and loading, simplifying your workflow.

- Repository: [Hunter Bown/DeepSeek-TUI](https://github.com/Hmbown/DeepSeek-TUI)
- Tags: architecture
- Published: 2026-05-04

---

**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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/skill.rs) orchestrates three distinct phases: resolution, formatting, and metadata packaging.

### Skill Resolution and Error Handling

Lines 87-94 in [`skill.rs`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/skill.rs) perform the registry lookup:

```rust
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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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:

```rust
// 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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/SKILL.md) file), and `companion_files` (an array of paths to sibling files in the skill directory, excluding [`SKILL.md`](https://github.com/Hmbown/DeepSeek-TUI/blob/main/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.