| name | bashticle |
| description | Create interactive bash articles (bashticles) from markdown blog posts with streaming text, command execution, and user interaction |
Bashticle
Transform markdown blog posts into interactive bash scripts that users can read and execute directly from their terminal.
When to Use
Use this skill when a user asks to:
- "Create a bashticle from this markdown"
- "Turn this article into an interactive bash script"
- "Make a terminal-based interactive article"
- "Convert blog.md to a bash article"
Two-Phase Approach
Bashticle creation uses a two-phase approach:
Phase 1: Generator Script (Boring, Structural)
The bashticle-generator.sh script does the structural work:
bashticle-generator.sh article.md
bashticle-generator.sh article.md --output-file custom.sh
What it does:
- Parses markdown for structure (title, sections)
- Generates basic bashticle with STANDARD options only
- Creates section function stubs
- Builds main navigation flow
Standard options included:
--step - Jump to specific section
--run-command / -r - Execute commands vs echo
--dry-run / -d - Echo only (default: ON)
--stream / -s - Enable streaming (default: ON)
--verbose / -v - Verbose output
Phase 2: AI (Smart, Context-Aware)
The AI (via this skill) enhances the bashticle:
- Read both files: Original markdown + generated bashticle
- Use
parseArger parse to add article-specific options:
parseArger parse bashticle.sh --inplace \
--opt 'ai-provider "AI provider" --short p --default-value "openrouter"' \
--opt 'ai-model "AI model" --short m' \
--opt 'api-key "API key" --short k' \
--opt 'project-name "Project name"' \
--opt 'reasoning "Reasoning tokens" --default-value "4096"'
- Fill in section functions with actual content
- Convert code blocks to command arrays with proper variable injection
What Gets Generated
A .sh file with:
- parseArger CLI - Full argument parsing with sensible defaults
- Helper functions - stream_text, print_section, prompt_continue, run_cmd, show_cmd
- Section stubs - One function per markdown section (AI fills these)
- Main flow - Navigation with
--step support
Example Workflow
bashticle-generator.sh article.md
Converting Markdown to Bash
Sections (## headers)
Each ## or ### header becomes a bash function:
## Getting Started
Content here...
Generated stub:
show_getting_started() {
print_section "Getting Started"
prompt_continue
}
AI fills in:
show_getting_started() {
print_section "Getting Started"
stream_text "Content here..."
local init_cmd=(npm install)
show_cmd "Install dependencies" npm install
run_cmd "${init_cmd[@]}"
prompt_continue
}
Code Blocks (```bash)
Code blocks are converted to command arrays with variable injection:
```bash
npx task-o-matic@latest init --project-name my-project
AI converts to:
```bash
local init_cmd=(
npx task-o-matic@latest init
--project-name "$_arg_project_name" # Variable injection
)
run_cmd "${init_cmd[@]}"
Helper Functions
stream_text "text" [delay]
print_section "title"
print_subsection "title"
prompt_continue
run_cmd arg1 arg2 ...
show_cmd "explanation" cmd ...
Available Variables
Variables from CLI arguments (after AI adds them):
$_arg_ai_provider
$_arg_ai_model
$_arg_api_key
$_arg_project_name
$_arg_reasoning
$_arg_stream
$_arg_run_command
$_arg_dry_run
$_arg_verbose
$_arg_step
Color Scheme
- Cyan (36): Section headers
- Yellow (33): Subsections
- Green (32): User prompts
- Magenta (35): Commands
- White (37): Explanations
- Gray (90): Dry-run messages
Examples
Generator creates:
show_init() {
print_section "Initialization"
prompt_continue
}
AI converts to:
show_init() {
print_section "Initialization"
stream_text "Let's initialize the project..."
echo ""
show_cmd "Initialize with task-o-matic" \
npx task-o-matic@latest init init \
--project-name "$_arg_project_name" \
--frontend tanstack-router
run_cmd npx task-o-matic@latest init init \
--project-name "$_arg_project_name" \
--frontend tanstack-router
echo ""
stream_text "Project initialized!"
echo ""
prompt_continue
}
Running Generated Bashticles
./bashticle.sh --help
./bashticle.sh
./bashticle.sh init
./bashticle.sh --run-command --ai-provider anthropic
./bashticle.sh --no-stream
Implementation Notes
What the Generator Does (Deterministic)
- Extract title from frontmatter or first heading
- Find all
## and ### sections
- Generate basic parseArger CLI with standard options
- Create section function stubs
- Build main navigation flow
- Always include helper functions
What the AI Does (Context-Aware)
- Analyze article content to determine needed options
- Use
parseArger parse to add relevant CLI options
- Fill in section functions with actual content
- Convert code blocks to command arrays
- Inject CLI variables into commands appropriately
- Handle article-specific patterns and conventions
Files
- Generator:
scripts/bashticle-generator.sh
- Example bashticle:
apps/web/content/blog/Black hole/From ralph to Eric/bashticle.sh
- Helpers reference:
references/helpers.md