textual-builder — Claude Code skill for Textual TUIs
The textual-builder skill guides agents through building terminal interfaces with Textual and prototyping card games. It includes references for widgets, layouts, styling, and interaction.
MIT 7 installs ★ 31 updated 2026-10-25
npx skills add YPares/agent-skills --skill textual-builder -a claude-codeWhat textual-builder does
textual-builder helps an agent create terminal and browser interfaces with Textual, a Python framework. Its reference files cover app structure, widgets, layout, CSS styling, and user input handling. Each topic has its own guide in references/.
For a card game prototype, start from assets/card-game-template/. The starter includes face-up and face-down cards, player hand areas, and turn handling; run it with python app.py. Textual v0.86.0 or later is required, so the app will not run without that dependency.
What it helps with
- scaffold a terminal app with Textual
- arrange widgets in grids and containers
- add inputs, buttons, or a data table
- wire keyboard bindings to event handlers
- start a card game prototype from a template
Example prompts for the agent
- Build a Textual terminal app with a header, main content area, and footer.
- Create a responsive Textual layout with a data table and input fields.
- Start a card game prototype from
assets/card-game-template/.
How to install textual-builder
1Skills CLI (Vercel)
npx skills add YPares/agent-skills --skill textual-builder -a claude-code2Manually: put the files in place
~/.claude/skills/textual-builder/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/textual-builder/
1Skills CLI (Vercel)
npx skills add YPares/agent-skills --skill textual-builder -a codex2Manually: put the files in place
.agents/skills/textual-builder/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add YPares/agent-skills --skill textual-builder -a cursor2Manually: put the files in place
.cursor/skills/textual-builder/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install YPares/agent-skills textual-builder2Manually: put the files in place
.github/skills/textual-builder/SKILL.md1Skills CLI (Vercel)
npx skills add YPares/agent-skills --skill textual-builder -a gemini-cli2Platform CLI
gemini skills install https://github.com/YPares/agent-skills --path textual-builderManually: put the files in place
.devin/skills/textual-builder/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add YPares/agent-skills --skill textual-builder -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about textual-builder
How do I install textual-builder in Claude Code?
Run npx skills add YPares/agent-skills --skill textual-builder -a claude-code. The skill file is at ~/.claude/skills/textual-builder/SKILL.md.
What does textual-builder do?
It guides an agent in making Textual interfaces, from widget layout and CSS styling to handling user actions. It also provides a starter project for card game prototypes.
Which Textual version does textual-builder require?
The skill requires Textual v0.86.0 or later. Install the package with pip install textual.
Source text
SKILL.md · MIT
---
name: textual-builder
description: Build Text User Interface (TUI) applications using the Textual Python framework (v0.86.0+). Use when creating terminal-based applications, prototyping card games or interactive CLIs, or when the user mentions Textual, TUI, or terminal UI. Includes comprehensive reference documentation, card game starter template, and styling guides.
---
# Textual Builder
## Overview
This skill helps you build sophisticated Text User Interfaces (TUIs) using Textual, a Python framework for creating terminal and browser-based applications with a modern web-inspired API. It includes reference documentation, a card game template, and best practices for Textual development.
## Quick Start
### Basic Textual App
```python
from textual.app import App, ComposeResult
from textual.widgets import Header, Footer, Label
class MyApp(App):
def compose(self) -> ComposeResult:
yield Header()
yield Label("Hello, Textual!")
yield Footer()
if __name__ == "__main__":
app = MyApp()
app.run()
```
### Card Game Template
For card game prototyping, copy the template:
```bash
cp -r assets/card-game-template/* ./my-game/
cd my-game
python app.py
```
The template includes:
- Interactive Card widget with face-up/down states
- Hand containers for player cards
- Play area with turn management
- Key bindings for card selection and playing
- Customizable styling
See `assets/card-game-template/README.md` for customization guide.
## When to Read Reference Documentation
This skill includes comprehensive reference files. Load them based on your task:
### references/basics.md
**Read when:** Setting up app structure, using reactive attributes, handling mounting, querying widgets, or working with messages/events.
**Covers:**
- App structure and compose method
- Reactive attributes and watchers
- Mounting and dynamic widget creation
- Widget querying
- Messages, events, and custom messages
### references/widgets.md
**Read when:** Adding UI elements like buttons, inputs, labels, data tables, or creating custom widgets.
**Covers:**
- Display widgets (Label, Static, Placeholder)
- Input widgets (Button, Input, TextArea, Switch)
- DataTable for tabular data
- Layout containers (Container, Grid, Horizontal, Vertical)
- Custom widget creation
- Header/Footer
### references/layout.md
**Read when:** Designing layouts, positioning widgets, using grid systems, or handling responsive sizing.
**Covers:**
- Layout types (vertical, horizontal, grid)
- Grid configuration (cell spanning, row/column sizing)
- Alignment and content positioning
- Docking widgets to screen edges
- Sizing (fixed, relative, fractional, auto)
- Spacing (margin, padding)
- Scrolling
### references/styling.md
**Read when:** Applying CSS styles, theming, adding borders, or customizing widget appearance.
**Covers:**
- CSS files and selectors
- Colors (named, hex, RGB, theme variables)
- Borders and border styling
- Text styling and alignment
- Opacity and tinting
- Rich markup for styled text
- Pseudo-classes (:hover, :focus, etc.)
### references/interactivity.md
**Read when:** Implementing keyboard shortcuts, handling mouse events, responding to user actions, or creating interactive behaviors.
**Covers:**
- Key bindings and actions
- Dynamic binding updates
- Mouse events (click, hover, enter, leave)
- Keyboard events
- Focus management
- Widget-specific messages
- Custom messages
- Notifications and timers
## Common Workflows
### Creating a New TUI App
1. Start with basic app structure (see Quick Start)
2. Design layout (read `references/layout.md`)
3. Add widgets (read `references/widgets.md`)
4. Style with CSS (read `references/styling.md`)
5. Add interactivity (read `references/interactivity.md`)
### Prototyping a Card Game
1. Copy the card game template
2. Customize the Card widget for your game's card properties
3. Modify game logic in action methods
4. Add game-specific rules in message handlers
5. Style cards and layout in `app.tcss`
### Adding Interactive Features
1. Define key bindings in `BINDINGS`
2. Implement action methods (`action_*`)
3. Handle widget messages (`on_button_pressed`, etc.)
4. Use reactive attributes for state management
5. Update UI in watchers
## Best Practices
- **Progressive Development**: Start simple, add complexity incrementally
- **Reactive State**: Use `reactive()` for state that affects UI
- **CSS Separation**: Keep styling in `.tcss` files, not inline
- **Widget Reuse**: Create custom widgets for repeated components
- **Message Bubbling**: Use `event.stop()` to control message propagation
- **Type Hints**: Use proper type hints for better IDE support
- **IDs and Classes**: Use semantic IDs/classes for querying and styling
## Installation
```bash
pip install textual
# or
uv pip install textual
```
Current version: v0.86.0+ (as of November 2025, latest is v6.6.0)
## Resources
### references/
Comprehensive documentation loaded on-demand:
- `basics.md` - Core concepts and app structure
- `widgets.md` - Widget catalog and usage
- `layout.md` - Layout systems and positioning
- `styling.md` - CSS and theming
- `interactivity.md` - Events, bindings, and actions
### assets/
- `card-game-template/` - Complete starter template for card games with interactive cards, hands, and turn management
## Official Documentation
For topics not covered in this skill, consult:
- https://textual.textualize.io/ (official docs)
- https://github.com/Textualize/textual (GitHub repo)
© YPares · MIT · YPares/agent-skills