Skip to main content
skill CX Codex

textual-tui-skill — Claude Code skill for Textual and setup

textual-tui-skill is a Claude Code skill for building Python terminal interfaces with Textual, covering widgets, styles, background tasks, and tests.

MIT 268 installs ★ 35 updated 2026-10-21

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add podo/design-agent-skills --skill textual-tui-skill -a claude-code
Open on GitHub

What textual-tui-skill does

This skill guides an agent through building Textual terminal apps in Python. Its coverage includes built-in widgets, vertical, horizontal and grid layouts, TCSS styling, reactive attributes, event handling, and navigation across screens. It also addresses modal dialogs and tests that drive the UI with the Pilot API.

The package includes reference material in references/ and four complete apps in assets/: a todo list, a system dashboard, a data viewer, and a worker demo. It explains pitfalls such as blocking the event loop and updating the UI safely from a thread. Generated apps require Python with textual and textual-dev; without those packages, they cannot run.

What it helps with

  • choose Textual widgets for a terminal app
  • arrange a TUI with grid or column layouts
  • style an interface using TCSS
  • run background work without blocking the event loop
  • test UI interactions with the Pilot API

Example prompts for the agent

  • Build a Textual app with a data table and navigation between screens.
  • Find why a background task blocks the event loop in my Textual app.
  • Write a pytest test that drives my Textual UI with the Pilot API.

How to install textual-tui-skill

1Skills CLI (Vercel)

npx skills add podo/design-agent-skills --skill textual-tui-skill -a claude-code

2Manually: put the files in place

~/.claude/skills/textual-tui-skill/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/textual-tui-skill/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about textual-tui-skill

How do I install textual-tui-skill in Claude Code?

Run npx skills add podo/design-agent-skills --skill textual-tui-skill -a claude-code. The skill file is at ~/.claude/skills/textual-tui-skill/SKILL.md.

What does textual-tui-skill do?

It helps build Python TUIs with Textual, covering widgets, layouts, TCSS, reactive behavior, workers, screen navigation, and Pilot API testing.

Which packages are needed to run generated apps?

Use Python with textual and textual-dev. The generated applications need both packages to run.

Source text

SKILL.md · MIT
---
name: textual-tui-skill
description: |
  Deep-dive Textual (Python) TUI skill: built-in widgets, layout systems, TCSS styling,
  reactive programming, background workers, multi-screen navigation, modal dialogs, and
  testing via the Pilot API. Covers common pitfalls and thread-safety rules for
  async/worker patterns, with working example apps.
triggers:
  - "Textual TUI"
  - "textual-tui-skill"
  - "Textual widget"
  - "Textual app"
  - "TCSS styling"
  - "Textual framework"
das:
  type: skill
  category: tui-terminal
  upstream: "https://github.com/aperepel/textual-tui-skill"
  upstream_path: "skill/SKILL.md"
  version: latest
---

# textual-tui-skill

> Catalogue stub — full skill: [aperepel/textual-tui-skill](https://github.com/aperepel/textual-tui-skill) (`textual-tui`)

<!-- das:install:start — generated from stub.yaml by `npm run generate`; edit stub.yaml, not this block -->
## Decision tree

1. **Is the full skill already installed?**
   Upstream names this skill `textual-tui`, so it installs next to this pointer (the pointer is not replaced).
   - Global: `f=~/.agents/skills/textual-tui/SKILL.md; [ -f "$f" ] && ! grep -q "^das:" "$f" && echo "installed" || echo "pointer"`
   - Project: `f=.agents/skills/textual-tui/SKILL.md; [ -f "$f" ] && ! grep -q "^das:" "$f" && echo "installed" || echo "pointer"`
   - `installed` → the skill is installed as `textual-tui`, invoke it and proceed
   - `pointer` → go to step 2

2. **Detect scope, then install:**

   ```bash
   [ -e ~/.agents/skills/textual-tui-skill ] && echo "global" || echo "project"
   ```

   **Global:**
   ```bash
   npx skills add aperepel/textual-tui-skill --skill textual-tui -g -y
   ```

   **Project:**
   ```bash
   npx skills add aperepel/textual-tui-skill --skill textual-tui -y
   ```
   > **Claude Code:** send a command as a chat message starting with `!` to run it without leaving the conversation.

**Heads-up**

- **Requires:** Python with textual and textual-dev (pip install textual textual-dev) to run what the skill generates
- **License:** MIT
<!-- das:install:end -->

## Invoke after install

- Skill name: `textual-tui`
- Trigger phrases: "Textual TUI", "Textual widget", "Textual app", "TCSS styling", "Textual framework"

## What it does

Comprehensive Textual framework reference for building professional Python TUIs:

| Area | Coverage |
|------|----------|
| **Widgets** | Built-in widgets such as Input, Button, Select, Checkbox, DataTable, Tree, Log, RichLog, Tabs, TabbedContent |
| **Layouts** | Vertical, Horizontal, Grid; fixed/fractional sizing; responsive patterns |
| **Styling** | TCSS syntax, semantic color system, external stylesheets, borders, padding |
| **Reactivity** | Reactive attributes, watchers, computed properties, DOM-like widget tree |
| **Async** | Workers for long-running tasks, `call_from_thread()` for thread-safe UI updates, cancellation |
| **Navigation** | Multi-screen apps, modal screens, screen stack management |
| **Events** | Mount, Click, Key; keyboard bindings; action methods; message propagation |
| **Testing** | Pilot API, async test patterns with pytest, UI interaction simulation |
| **Pitfalls** | Common mistakes documented: blocking the event loop, thread safety, worker selection |

Ships `references/` (widgets, layouts, styling, an index of the official guides) and four complete example apps under `assets/`: a todo app, a system dashboard, a data viewer and a worker demo.

## When NOT to use

- Multi-framework TUI overview (Go/Rust/Python/TS) — use `tui-design-skill`
- Bubble Tea (Go) — use `tui-design-skill`
- Ratatui (Rust) — use `tui-design-skill`
- Ink (TypeScript/React) — use `tui-design-skill`

© podo · MIT · podo/design-agent-skills

Similar skills

All skills for Frontend and UI →

From the same set108

The whole set →
antvis-chart-skills antvis-chart-skills is a Claude Code skill for creating charts, diagrams, and infographics with AntV, including data visualization and turning text into diagrams. CX Codex +1 277installs figma-official-skills figma-official-skills is a Claude Code skill package that moves Figma designs into code, builds design-system libraries and links Figma components to repository components. CX Codex +1 271installs shadcn-ui Guides AI coding agents through searching, adding, and composing shadcn/ui components accurately. CX Codex +1 271installs deanpeters-pm-skills deanpeters-pm-skills — a skill for Claude Code, Codex and Cursor: nine product management techniques — NNGroup customer journey maps, Lean UX Canvas, Teresa Torres opportunity-solution trees, proto-personas, user story mapping. CX Codex +1 270installs remotion remotion is a Claude Code skill for building videos from React components, with spring-driven motion and export to MP4, WebM or GIF. CX Codex +1 265installs user-research-cookiy user-research-cookiy is a Claude Code skill for planning user research, creating discussion guides, and synthesizing transcripts in an agent workspace. CX Codex +1 264installs framer-motion-skills Five Framer Motion skills for React and Next.js: variants, scroll-linked effects, gestures and shared layout transitions. One command installs them all. CX Codex +1 264installs wcag-ai-skill The wcag-ai-skill skill turns WCAG 2.2 criteria into working guidance for design, implementation, accessibility checks, remediation, and conformance docs. Use it across a project’s accessibility workflow. CX Codex +1 244installs

Project sponsors

Companies that keep this analytics open