Terminal User Interface (TUI)
Relevant source files
The following files were used as context for generating this wiki page:
The Terminal User Interface (TUI) is an interactive visual management system for the SkillKit ecosystem. It allows users to browse, install, translate, and manage AI agent skills directly within the terminal using a responsive design that adapts to various terminal sizes. Sources: packages/tui/README.md:5-18
The TUI serves as a high-level orchestration layer over @skillkit/core, providing a project-aware interface for cross-agent skill translation and management. It is built using the Ink framework, which brings React-based component architecture to command-line interfaces. Sources: packages/tui/README.md:120-130, packages/tui/package.json:23-28
System Architecture
The TUI architecture follows a React-based component pattern tailored for terminal rendering. It integrates tightly with the core logic for skill discovery and translation.
The diagram above illustrates the component hierarchy where the main application entry point manages state and navigation across specialized screen components. Sources: packages/tui/README.md:120-143
Core Technologies
The TUI leverages a modern JavaScript stack for terminal applications:
- Ink: React for CLI components.
- React: Core component lifecycle and state management.
- @skillkit/core: Provides the underlying data and logic for skills.
- Chalk: Terminal string styling.
Sources: packages/tui/package.json:22-30, packages/tui/README.md:120-125
Features and Navigation
The TUI is organized into functional "screens" accessible via single-key shortcuts. These screens provide visual interfaces for complex CLI operations such as project analysis and skill synchronization. Sources: packages/tui/README.md:23-90
Screen Modules
| Screen | Key | Purpose |
|---|---|---|
| Home | h | Overview of detected agents, project status, and navigation hints. |
| Marketplace | m | Browse 33+ repositories with search and popularity metrics. |
| Recommend | r | AI-powered suggestions based on package.json and file structure. |
| Translate | t | Convert skills between any of the 17 supported agent formats. |
| Context | c | Manage detected languages, frameworks, and testing tools. |
| Installed | i | View, enable, disable, or remove installed skills. |
Sources: packages/tui/README.md:23-85, packages/cli/src/commands/recommend.ts:25-50
Skill Translation and Management
A primary function of the TUI is facilitating the cross-agent ecosystem. It utilizes the skill-translator to move skills between formats like Claude Code (XML), Cursor (MDC), and GitHub Copilot (Markdown). Sources: packages/core/src/skill-translator.ts:10-25, packages/tui/README.md:12-15
Translation Flow
When a user selects a skill for translation in the TUI, the system performs the following sequence:
The TUI acts as the visual coordinator for the translation engine, allowing users to preview changes and warnings before applying them to the disk. Sources: packages/core/src/skill-translator.ts:182-205, packages/tui/README.md:73-77
Interaction and Controls
The TUI supports a wide array of keyboard shortcuts for navigation and interaction within lists and forms. Sources: packages/tui/README.md:92-113
Navigation Shortcuts
- Arrows (↑/↓): Navigate through skill lists or menu options.
- Enter: Confirm selections or toggle installation.
- /: Activate search mode for filtering skills by name or tag.
- Tab: Switch focus between different UI panels (e.g., list vs. detail view).
- Esc: Return to the previous screen or close search.
Sources: packages/tui/README.md:108-113
Technical Requirements and Usage
The TUI is launched via the skillkit ui command. It requires a terminal environment that supports ANSI or True Color for optimal rendering. Sources: packages/tui/README.md:18-21, packages/tui/README.md:145-148
Programmatic Invocation
The interface can be started programmatically by importing the startTUI function from @skillkit/tui.
import { startTUI } from '@skillkit/tui';
// Launch with custom project path and initial screen
await startTUI({
projectPath: './my-project',
initialScreen: 'recommend',
theme: 'dark',
});
Sources: packages/tui/README.md:115-125
Summary
The SkillKit TUI provides a visual and interactive layer that simplifies the management of complex AI agent skills. By abstracting the underlying translation logic and project analysis into discrete screens, it enables developers to maintain a project-aware skill context across 17 different AI agents efficiently. Sources: packages/tui/README.md:5-18, packages/CONTRIBUTING.md:25-35