@xonovex/skills 0.1.0

package/skills/remotion-guidelines/reference/transitions.md

@@ -0,0 +1,52 @@
+# transitions: Scene Transitions
+
+**Guideline:** Use `<TransitionSeries>` from `@remotion/transitions` for fullscreen scene transitions.
+
+**Rationale:** Transitions overlap scenes, reducing total composition duration. `<TransitionSeries>` handles complex timing automatically.
+
+**Example:**
+```tsx
+import { TransitionSeries } from '@remotion/transitions'
+import { linearTiming, springTiming } from '@remotion/transitions'
+import { fade, slide } from '@remotion/transitions'
+import { useVideoConfig } from 'remotion'
+
+export const MyComposition = () => {
+  const { fps } = useVideoConfig()
+
+  return (
+    <TransitionSeries>
+      <TransitionSeries.Sequence durationInFrames={2 * fps}>
+        <Scene1 />
+      </TransitionSeries.Sequence>
+      <TransitionSeries.Transition
+        timing={linearTiming({ durationInFrames: 0.5 * fps })}
+        effect={fade()}
+      />
+      <TransitionSeries.Sequence durationInFrames={3 * fps}>
+        <Scene2 />
+      </TransitionSeries.Sequence>
+      <TransitionSeries.Transition
+        timing={springTiming({ durationInFrames: 0.75 * fps })}
+        effect={slide({ direction: 'from-left' })}
+      />
+      <TransitionSeries.Sequence durationInFrames={2 * fps}>
+        <Scene3 />
+      </TransitionSeries.Sequence>
+    </TransitionSeries>
+  )
+  // Total: (2 + 0.5 + 3 + 0.75 + 2) * fps frames
+}
+```
+
+**Techniques:**
+- Install `@remotion/transitions` package before use
+- Wrap all scenes with `<TransitionSeries>` container
+- Use `<TransitionSeries.Sequence>` for each scene's content
+- Add `<TransitionSeries.Transition>` between sequences for effects
+- Account for overlap in duration math: `total = scene1 + scene2 - transition`
+- Choose transition effect: `fade()`, `slide({direction})`, `wipe({direction})`, `flip({direction})`, `clockWipe()`
+- Set timing with `linearTiming({durationInFrames})` for constant speed
+- Use `springTiming({config, durationInFrames})` for animated spring transitions
+- Calculate total duration accounting for overlapping transitions
+- Test duration math carefully to ensure smooth transitions

package/skills/shell-scripting-guidelines/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: shell-scripting-guidelines
+description: >-
+  Trigger on `.sh` files and shell scripts. Use when writing POSIX shell scripts for automation. Apply for strict mode, quoting, error handling, idempotent operations. Keywords: shell, bash, POSIX, shellcheck, shfmt, strict mode, quoting, parameter expansion, exit codes, idempotency.
+---
+
+# Shell Scripting Coding Guidelines
+
+## Essentials
+
+- **POSIX compatibility** - Use POSIX sh, lint with shellcheck, format with shfmt, see [reference/posix-compatibility.md](reference/posix-compatibility.md)
+- **Strict mode** - Use strict mode and safe defaults, see [reference/strict-mode.md](reference/strict-mode.md)
+- **Quoting** - Quote all expansions to avoid word splitting, see [reference/quoting.md](reference/quoting.md)
+- **Functions** - Write small, focused functions, see [reference/functions.md](reference/functions.md)
+- **Parameter expansion** - Set default values and manipulate variables, see [reference/parameter-expansion.md](reference/parameter-expansion.md)
+- **Error handling** - Implement exit codes and error messages, see [reference/error-handling.md](reference/error-handling.md)
+- **Idempotency** - Make scripts safely re-runnable, see [reference/idempotency.md](reference/idempotency.md)
+
+## Progressive disclosure
+
+- Read [reference/posix-compatibility.md](reference/posix-compatibility.md) - When ensuring portability across shells
+- Read [reference/strict-mode.md](reference/strict-mode.md) - When setting up error handling and safety flags
+- Read [reference/quoting.md](reference/quoting.md) - When variables expand incorrectly or word splitting occurs
+- Read [reference/functions.md](reference/functions.md) - When organizing script logic or creating reusable code
+- Read [reference/parameter-expansion.md](reference/parameter-expansion.md) - When setting default values or manipulating variables
+- Read [reference/error-handling.md](reference/error-handling.md) - When implementing exit codes or error messages
+- Read [reference/argument-parsing.md](reference/argument-parsing.md) - When parsing command-line flags or arguments
+- Read [reference/validation.md](reference/validation.md) - When checking preconditions or input validity
+- Read [reference/idempotency.md](reference/idempotency.md) - When scripts should be safely re-runnable
+- Read [reference/common-patterns.md](reference/common-patterns.md) - When learning common shell idioms
+- Read [reference/script-template.md](reference/script-template.md) - When starting a new shell script

package/skills/shell-scripting-guidelines/reference/argument-parsing.md

@@ -0,0 +1,67 @@
+# argument-parsing: Argument Parsing
+
+**Guideline:** Validate script arguments and parse flags with clear usage messages.
+
+**Rationale:** Proper argument parsing prevents script misuse, provides helpful feedback to users, and makes scripts more robust and user-friendly.
+
+**Example:**
+
+```sh
+# ✅ Simple argument parsing
+parse_args() {
+    if [ "$#" -lt 1 ]; then
+        die "Usage: $0 <input> [output]" 2
+    fi
+
+    input="$1"
+    output="${2:-output.txt}"
+
+    if [ ! -f "$input" ]; then
+        die "Input file not found: $input" 2
+    fi
+}
+
+# ✅ Flag parsing
+parse_flags() {
+    verbose=0
+    force=0
+
+    while [ "$#" -gt 0 ]; do
+        case "$1" in
+            -v|--verbose)
+                verbose=1
+                shift
+                ;;
+            -f|--force)
+                force=1
+                shift
+                ;;
+            -h|--help)
+                show_usage
+                exit 0
+                ;;
+            -*)
+                die "Unknown option: $1" 2
+                ;;
+            *)
+                break
+                ;;
+        esac
+    done
+
+    # Remaining args
+    if [ "$#" -lt 1 ]; then
+        die "Missing required argument" 2
+    fi
+
+    input="$1"
+}
+```
+
+**Techniques:**
+- Check argument count before accessing positional parameters
+- Provide clear usage messages showing required and optional arguments
+- Use a while loop with case statement for flag parsing
+- Support both short (-v) and long (--verbose) flags
+- Handle unknown flags with an error message
+- Validate argument values after parsing

package/skills/shell-scripting-guidelines/reference/common-patterns.md

@@ -0,0 +1,46 @@
+# common-patterns: Common Patterns
+
+**Guideline:** Use well-tested patterns for common operations like reading files, processing output, and managing temporary resources.
+
+**Rationale:** Standard patterns are proven to handle edge cases correctly and avoid common pitfalls like word splitting, missing the last line, or resource leaks.
+
+**Example:**
+
+```sh
+# ✅ Read file line by line
+while IFS= read -r line; do
+    process_line "$line"
+done < "$input_file"
+
+# ✅ Process command output
+find . -name '*.txt' | while IFS= read -r file; do
+    process_file "$file"
+done
+
+# ✅ Temporary directory
+temp_dir="$(mktemp -d)"
+trap 'rm -rf "$temp_dir"' EXIT
+
+# ✅ Check if running as root
+if [ "$(id -u)" -eq 0 ]; then
+    log "Running as root"
+fi
+
+# ✅ Get script directory
+script_dir="$(cd "$(dirname "$0")" && pwd)"
+
+# ✅ Check exit status
+if command arg1 arg2; then
+    log "Command succeeded"
+else
+    error "Command failed with exit code: $?"
+fi
+```
+
+**Techniques:**
+- Use `while IFS= read -r line` to read files line by line
+- Create temp files/dirs with `mktemp` and always trap cleanup
+- Use command substitution in conditionals for proper error handling
+- Get script directory with `cd "$(dirname "$0")" && pwd`
+- Check root with `[ "$(id -u)" -eq 0 ]`
+- Preserve IFS in read loops to handle whitespace correctly

package/skills/shell-scripting-guidelines/reference/error-handling.md

@@ -0,0 +1,62 @@
+# error-handling: Error Handling
+
+**Guideline:** Provide clear error messages with context, validate operations, and implement cleanup handlers.
+
+**Rationale:** Good error handling makes scripts easier to debug and prevents resource leaks. Clear error messages help users understand and fix problems quickly.
+
+**Example:**
+
+```sh
+# ✅ Clear error messages with context
+die() {
+    printf 'ERROR: %s\n' "$1" >&2
+    exit "${2:-1}"
+}
+
+# ✅ Check command existence
+require_command() {
+    local cmd="$1"
+    if ! command -v "$cmd" >/dev/null 2>&1; then
+        die "Required command not found: $cmd" 127
+    fi
+}
+
+# ✅ Validate file operations
+read_config() {
+    local config="$1"
+
+    if [ ! -f "$config" ]; then
+        die "Config file not found: $config" 2
+    fi
+
+    if [ ! -r "$config" ]; then
+        die "Config file not readable: $config" 2
+    fi
+
+    cat "$config"
+}
+
+# ✅ Cleanup on exit
+cleanup() {
+    local exit_code=$?
+    if [ -n "${temp_file:-}" ]; then
+        rm -f "$temp_file"
+    fi
+    exit "$exit_code"
+}
+
+trap cleanup EXIT INT TERM
+
+# Create temp file
+temp_file="$(mktemp)"
+# Use temp_file...
+# Cleanup happens automatically
+```
+
+**Techniques:**
+- Create a `die()` function for fatal errors with exit codes
+- Check command existence with `command -v`
+- Validate file operations before performing them
+- Use trap to ensure cleanup on exit, interrupt, or termination
+- Include context in error messages (filenames, expected values)
+- Use appropriate exit codes (0=success, 1=general error, 2=usage error, 127=command not found)

package/skills/shell-scripting-guidelines/reference/functions.md

@@ -0,0 +1,66 @@
+# functions: Function Best Practices
+
+**Guideline:** Write small, focused functions with local variables and meaningful return codes.
+
+**Rationale:** Small functions improve readability, testability, and reusability. Local variables prevent variable pollution, and return codes enable proper error handling.
+
+**Example:**
+
+```sh
+# ✅ Small focused functions
+is_file() {
+    [ -f "$1" ]
+}
+
+is_dir() {
+    [ -d "$1" ]
+}
+
+file_exists() {
+    [ -e "$1" ]
+}
+
+# ✅ Use local variables
+process_file() {
+    local file="$1"
+    local output="$2"
+
+    if ! is_file "$file"; then
+        error "Not a file: $file"
+        return 1
+    fi
+
+    # Process file...
+    log "Processed: $file -> $output"
+}
+
+# ✅ Return status codes
+validate_input() {
+    local input="$1"
+
+    if [ -z "$input" ]; then
+        return 1
+    fi
+
+    if [ "${#input}" -lt 3 ]; then
+        return 2
+    fi
+
+    return 0
+}
+
+# Usage
+if validate_input "$user_input"; then
+    log "Valid input"
+else
+    die "Invalid input" "$?"
+fi
+```
+
+**Techniques:**
+- Keep functions focused on a single task
+- Declare all function variables as `local`
+- Return 0 for success, non-zero for failure
+- Use descriptive function names (verb_noun format)
+- Validate function arguments before use
+- Use return codes, not exit, within functions

package/skills/shell-scripting-guidelines/reference/idempotency.md

@@ -0,0 +1,57 @@
+# idempotency: Idempotent Scripts
+
+**Guideline:** Design scripts to be safely run multiple times without unintended side effects.
+
+**Rationale:** Idempotent scripts are essential for automation, deployment, and configuration management. They allow safe retries after failures and prevent duplicate operations.
+
+**Example:**
+
+```sh
+# ✅ Check before creating
+create_directory() {
+    local dir="$1"
+
+    if [ -d "$dir" ]; then
+        log "Directory exists: $dir"
+        return 0
+    fi
+
+    mkdir -p "$dir"
+    log "Created directory: $dir"
+}
+
+# ✅ Check before modifying
+ensure_line_in_file() {
+    local line="$1"
+    local file="$2"
+
+    if grep -qF "$line" "$file" 2>/dev/null; then
+        log "Line already present: $file"
+        return 0
+    fi
+
+    printf '%s\n' "$line" >> "$file"
+    log "Added line to: $file"
+}
+
+# ✅ Atomic operations with temp files
+update_config() {
+    local config="$1"
+    local temp
+    temp="$(mktemp)"
+
+    # Generate new config
+    generate_config > "$temp"
+
+    # Atomic replace
+    mv "$temp" "$config"
+}
+```
+
+**Techniques:**
+- Check if resources exist before creating them
+- Use conditional operations that skip when already done
+- Use atomic operations with temporary files
+- Log actions taken vs. skipped for observability
+- Use `mkdir -p` and similar idempotent commands
+- Verify state before and after modifications

package/skills/shell-scripting-guidelines/reference/parameter-expansion.md

@@ -0,0 +1,38 @@
+# parameter-expansion: Default Values and Parameter Expansion
+
+**Guideline:** Use parameter expansion to set default values, require variables, and perform string operations.
+
+**Rationale:** Parameter expansion provides safe, portable ways to handle optional and required variables without external commands, improving script robustness and performance.
+
+**Example:**
+
+```sh
+# ✅ Default value if unset or empty
+: "${CONFIG_FILE:=/etc/app/config.conf}"
+: "${PORT:=8080}"
+: "${DEBUG:=0}"
+
+# ✅ Default value only if unset (keeps empty string)
+: "${NAME:=default}"
+
+# ✅ Use in assignments
+config="${CONFIG_FILE:-/etc/default.conf}"
+
+# ✅ Error if variable unset
+: "${REQUIRED_VAR:?Variable REQUIRED_VAR must be set}"
+
+# ✅ Alternate value if set
+message="${DEBUG:+Debug mode enabled}"
+
+# ✅ String operations
+filename="document.txt"
+basename="${filename%.*}"      # document
+extension="${filename##*.}"    # txt
+```
+
+**Techniques:**
+- Use `${VAR:-default}` for default if unset or empty
+- Use `: "${VAR:=value}"` to set defaults
+- Use `${VAR:?message}` to require variables
+- Use `${VAR:+value}` for alternate values when set
+- Use `${var%pattern}` and `${var##pattern}` for string operations

package/skills/shell-scripting-guidelines/reference/posix-compatibility.md

@@ -0,0 +1,53 @@
+# posix-compatibility: POSIX Compatibility
+
+**Guideline:** Use POSIX-compliant syntax for maximum portability across different shells and systems.
+
+**Rationale:** POSIX-compliant scripts run on any POSIX shell (sh, dash, bash, zsh, etc.), ensuring scripts work reliably across different systems without modification.
+
+**Example:**
+
+```sh
+# ✅ Use POSIX test constructs
+if [ -f "$file" ]; then
+    log "File exists"
+fi
+
+# ❌ Avoid bash-specific [[
+if [[ -f $file ]]; then  # Not POSIX
+    log "File exists"
+fi
+
+# ✅ POSIX string comparison
+if [ "$status" = "success" ]; then
+    log "Success"
+fi
+
+# ✅ POSIX numeric comparison
+if [ "$count" -gt 10 ]; then
+    log "Count exceeds 10"
+fi
+
+# ✅ POSIX command existence check
+if command -v git >/dev/null 2>&1; then
+    log "git is available"
+fi
+
+# ❌ Avoid type/which
+if type git >/dev/null 2>&1; then  # Less portable
+    log "git is available"
+fi
+
+# ✅ POSIX-compatible string operations
+string="hello world"
+# Use parameter expansion instead of bash ${var^^}
+upper="$(printf '%s' "$string" | tr '[:lower:]' '[:upper:]')"
+```
+
+**Techniques:**
+- Use `[ ]` instead of bash-specific `[[ ]]`
+- Use `=` for string comparison, not `==`
+- Use `-gt`, `-lt`, etc. for numeric comparisons
+- Use `command -v` instead of `which` or `type`
+- Use `tr` and `cut` instead of bash string operations
+- Avoid bash arrays, use positional parameters or temp files
+- Test scripts with `sh` (dash) not just bash

package/skills/shell-scripting-guidelines/reference/quoting.md

@@ -0,0 +1,42 @@
+# quoting: Quoting Variables and Expansions
+
+**Guideline:** Always quote variable expansions with double quotes to prevent word splitting and glob expansion.
+
+**Rationale:** Unquoted variables are subject to word splitting on whitespace and pathname expansion, leading to subtle bugs when filenames contain spaces or special characters.
+
+**Example:**
+
+```sh
+# ✅ Always quote variable expansions
+name="John Doe"
+log "Hello, $name"
+file="/path/to/my file.txt"
+cat "$file"
+
+# ❌ Unquoted variables cause word splitting
+cat $file  # Tries to cat "/path/to/my" and "file.txt" separately!
+
+# ✅ Quote arrays in loops
+for file in "$@"; do
+    process "$file"
+done
+
+# ❌ Unquoted $@ splits on spaces
+for file in $@; do  # Wrong!
+    process "$file"
+done
+
+# ✅ Use "${var}" for clarity
+config_file="${CONFIG_DIR}/app.conf"
+
+# ✅ Quote command substitution
+current_date="$(date +%Y-%m-%d)"
+files="$(find . -name '*.txt')"
+```
+
+**Techniques:**
+- Quote all variable expansions: `"$var"`
+- Quote command substitutions: `"$(command)"`
+- Quote `"$@"` in loops to preserve arguments with spaces
+- Use `"${var}"` for clarity in complex expansions
+- Never use unquoted variables in file operations

package/skills/shell-scripting-guidelines/reference/script-template.md

@@ -0,0 +1,70 @@
+# script-template: Basic Script Template
+
+**Guideline:** Start all shell scripts with a standard template including shebang, strict mode, logging functions, and argument validation.
+
+**Rationale:** A consistent template ensures scripts follow safety best practices from the start, reducing common errors and improving maintainability.
+
+**Example:**
+
+```sh
+#!/usr/bin/env sh
+# Description: Brief description of what this script does
+# Usage: script.sh <arg1> [arg2]
+
+set -eu  # Exit on error, error on undefined variable
+# Note: pipefail not in POSIX, use only if targeting bash
+
+# Default values
+: "${TMPDIR:=/tmp}"
+: "${VERBOSE:=0}"
+
+# Logging functions
+log() {
+    printf '%s\n' "$@"
+}
+
+log_verbose() {
+    if [ "$VERBOSE" = "1" ]; then
+        printf '[VERBOSE] %s\n' "$@" >&2
+    fi
+}
+
+error() {
+    printf 'ERROR: %s\n' "$@" >&2
+}
+
+die() {
+    error "$1"
+    exit "${2:-1}"
+}
+
+# Check requirements
+command -v required_tool >/dev/null 2>&1 || die "required_tool not found" 2
+
+# Validate arguments
+if [ "$#" -lt 1 ]; then
+    die "Usage: $0 <name> [options]" 2
+fi
+
+# Main logic
+main() {
+    local name="$1"
+    log "Processing: $name"
+
+    # Do work...
+
+    log "Done"
+}
+
+# Run main
+main "$@"
+```
+
+**Techniques:**
+- Begin with `#!/usr/bin/env sh` for portability
+- Add script description and usage in comments
+- Set strict mode with `set -eu`
+- Define logging and error functions
+- Check for required dependencies
+- Validate arguments before processing
+- Implement main logic in a main() function

package/skills/shell-scripting-guidelines/reference/strict-mode.md

@@ -0,0 +1,41 @@
+# strict-mode: Strict Mode and Safety
+
+**Guideline:** Enable strict mode with `set -eu` (POSIX) or `set -euo pipefail` (bash/zsh) to catch errors early.
+
+**Rationale:** Strict mode prevents scripts from continuing after errors, catches undefined variable usage, and makes pipeline failures visible, preventing silent failures that can cause data loss or security issues.
+
+**Example:**
+
+```sh
+# ✅ Basic strict mode (POSIX)
+set -eu
+
+# ✅ Full strict mode (bash/zsh)
+set -euo pipefail
+
+# What each flag does:
+# -e: Exit immediately if command fails
+# -u: Error on undefined variable
+# -o pipefail: Fail if any command in pipeline fails
+
+# ✅ Safer alternative for POSIX (no pipefail)
+set -eu
+IFS=$(printf '\n\t')
+
+# ✅ Handle expected failures explicitly
+if ! command_that_might_fail; then
+    log "Expected failure occurred"
+fi
+
+# ✅ Temporary disable strict mode
+set +e
+optional_command || true
+set -e
+```
+
+**Techniques:**
+- Add `set -eu` at the top of POSIX scripts
+- Add `set -euo pipefail` for bash/zsh scripts
+- Handle expected failures explicitly with `if ! command; then`
+- Temporarily disable strict mode only when necessary
+- Set IFS to newline and tab for POSIX compatibility

package/skills/shell-scripting-guidelines/reference/validation.md

@@ -0,0 +1,30 @@
+# validation: Shellcheck and Shfmt Integration
+
+**Guideline:** Validate scripts with shellcheck and format with shfmt for consistent, error-free code.
+
+**Rationale:** Shellcheck catches common bugs, portability issues, and anti-patterns automatically. Shfmt ensures consistent formatting across scripts, improving readability and maintainability.
+
+**Example:**
+
+```sh
+# Run shellcheck on script
+shellcheck script.sh
+
+# Check all shell scripts in directory
+find . -name '*.sh' -exec shellcheck {} +
+
+# Disable specific warnings (use sparingly)
+# shellcheck disable=SC2086
+variable_without_quotes=$1
+
+# Better: Fix the actual issue
+variable_with_quotes="$1"
+```
+
+**Techniques:**
+- Run `shellcheck script.sh` before committing
+- Use `find . -name '*.sh' -exec shellcheck {} +` to check multiple scripts
+- Fix shellcheck warnings rather than disabling them
+- Format scripts with `shfmt -w script.sh`
+- Use shfmt options: `-i 2` (2-space indent), `-bn` (binary ops), `-ci` (case indent), `-sr` (space after redirect)
+- Integrate shellcheck and shfmt into CI/CD pipelines