aia 1.0.0.pre.beta → 1.1.0

data/README.md

@@ -7,17 +7,11 @@
 
 ---
 
-> ## ⚠️ BREAKING CHANGES IN v0.10.* ⚠️
->
-> **Version 0.10.0 introduces breaking changes affecting:**
->
-> - **Environment Variables** — Naming conventions now use double underscore (`__`) for nested config sections (e.g., `AIA_LLM__TEMPERATURE`, `AIA_FLAGS__DEBUG`). See [Environment Variables](https://madbomber.github.io/aia/configuration/#environment-variables) for the complete list.
->
-> - **Configuration Files** — Configuration now uses a nested YAML structure with sections like `llm:`, `prompts:`, `output:`, `flags:`, etc. The [defaults.yml](lib/aia/config/defaults.yml) file is the single source of truth for all configuration options. See [Configuration Guide](https://madbomber.github.io/aia/configuration/) for details.
->
-> - **File Locations** — Configuration files now follow the XDG Base Directory Specification. The default config file location is `~/.config/aia/aia.yml`. See [Installation Guide](https://madbomber.github.io/aia/installation/) for setup instructions.
->
-> **Review the [Configuration Guide](https://madbomber.github.io/aia/configuration/) before upgrading to v0.10.0.**
+> ### 🚀 New: AI Assistant Scheduler (AIAS)
+> **Schedule and automate your AIA prompts!** AIAS is a new Ruby gem that lets you run AIA prompts on a cron-like schedule — perfect for recurring AI tasks, automated reports, and timed workflows.
+> **[View AIAS on GitHub →](https://github.com/madbomber/aias)**
+
+---
 
 ---
 
@@ -70,9 +64,9 @@ For more information on AIA visit these locations:
 ```plain
 
        ,      ,
-       (\____/) AI Assistant (v0.9.7) is Online
+       (\____/) AI Assistant (v1.1.0) is Online
         (_oo_)   gpt-4o-mini
-         (O)       using ruby_llm (v1.3.1)
+         (O)       using ruby_llm
        __||__    \) model db was last refreshed on
      [/______\]  /    2025-06-18
     / \__AI__/ \/      You can share my tools
@@ -122,6 +116,114 @@ Implement a schema registry with event-driven synchronization...
 
 ---
 
+## 🎭 Give Your Robot a Personality with Roles
+
+Why settle for a generic AI when you can have **your** robot? A role is a plain-text file that defines how your AI thinks, talks, and interacts with you. Drop it in `~/.prompts/roles/`, point AIA at it, and your robot instantly becomes someone new.
+
+**For fun — because AI doesn't have to be boring:**
+
+```bash
+# Ahoy! Your AI now talks like a salty sea pirate
+aia --chat --role pirate
+
+# Opinionated New York cabbie who has thoughts on EVERYTHING
+aia --chat --role nyc_cabbie
+
+# That stoned hacker buddy who somehow solves every problem
+aia --chat --role stoned_hacker
+```
+
+Create `~/.prompts/roles/pirate.md`:
+```
+Arrr, ye be speakin' with the most knowledgeable AI pirate to ever sail the
+digital seas! Answer every question in authentic pirate speak, drop nautical
+references, and sign off with "Arrr!" No matter how technical the topic,
+keep the pirate spirit alive, matey.
+```
+
+**For serious work — productive personas that deliver results:**
+
+```bash
+# Explains quantum physics to your 7-year-old
+aia --chat --role first_grade_teacher
+
+# Three expert robots reviewing the same design doc simultaneously
+aia --model gpt-4o=architect,claude=security,gemini=performance design.md
+
+# Same question, three philosophical stances
+aia --model gpt-4o=optimist,gpt-4o=pessimist,gpt-4o=realist business_plan.md
+```
+
+Create `~/.prompts/roles/first_grade_teacher.md`:
+```
+You are a patient, enthusiastic first-grade teacher with a magical gift: you can
+explain ANY complex subject using simple words and everyday analogies — toys,
+animals, food, playground games. Your mission is to make hard things feel easy
+and exciting. Never use jargon. Always encourage. Keep it fun!
+```
+
+Assign a different role to each model and get multiple expert perspectives on the same question in one command. Every robot, its own voice.
+
+---
+
+## 🎓 Teach Your Robot New Skills
+
+Skills are structured instruction sets that tell your robot *exactly how* to approach a task — your workflow, your standards, every single time. No more repeating yourself in every prompt.
+
+A skill is a directory containing a `SKILL.md` file with YAML front matter and the process you want your robot to follow. Create one for any repeatable task.
+
+**Apply skills in seconds:**
+
+```bash
+# Prepend a skill to any prompt
+aia -s code-quality my_prompt
+
+# Stack multiple skills — they apply in order
+aia -s code-quality,security-review,add-tests my_prompt
+
+# Chat mode: skills prime the entire session from the start
+aia --chat --role senior_dev -s code-quality
+
+# Add a skill mid-chat with the /skill directive
+/skill code-quality
+```
+
+Create `~/.prompts/skills/code-quality/SKILL.md`:
+```markdown
+---
+name: Code Quality
+description: Enforce SOLID principles and team coding standards
+---
+When reviewing code, evaluate in this exact order:
+
+1. **SOLID Principles** — name any violations explicitly
+2. **Security** — flag injection risks, exposed credentials, unsafe inputs
+3. **Performance** — O(n²) or worse, unnecessary allocations, N+1 queries
+4. **Readability** — method names, variable names, comment quality
+5. **Test Coverage** — are edge cases covered? Behavior, not implementation?
+
+Format: Summary → Issues by category → Suggested rewrites
+```
+
+**Combine roles AND skills for a fully customized robot:**
+
+```bash
+# A pirate who also follows your exact code review process
+aia --chat --role pirate -s code-quality
+
+# A first-grade teacher who uses your step-by-step explanation method
+aia --chat --role first_grade_teacher -s explain-with-analogies
+
+# Multiple robots, each with its own role and skill set
+aia --model gpt-4o=architect,claude=security \
+    -s architecture-review,threat-model \
+    design.md
+```
+
+Skills accumulate — specify multiple with commas or repeat `-s`. Each skill is prepended to your prompt in order, establishing exactly the context you want before the AI sees your actual question. Pair with roles for robots that are both *who you want* and *know what to do*.
+
+---
+
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
 ## Table of Contents
@@ -264,8 +366,11 @@ aia --fuzzy
 | `--model MODEL` | Specify AI model(s) to use. Supports `MODEL[=ROLE]` syntax | `aia --model gpt-4o-mini,gpt-3.5-turbo` or `aia --model gpt-4o=architect,claude=security` |
 | `--consensus` | Enable consensus mode for multi-model | `aia --consensus` |
 | `--no-consensus` | Force individual responses | `aia --no-consensus` |
-| `--role ROLE` | Use a role/system prompt (default for all models) | `aia --role expert` |
+| `--role ROLE` | Use a role/system prompt; accepts an ID in `~/.prompts/roles/` or a path (`/`, `~/`, `./`, `../`) | `aia --role expert` or `aia --role ~/custom/role.md` |
 | `--list-roles` | List available role files | `aia --list-roles` |
+| `-s, --skill SKILL_IDS` | Prepend skill(s) to prompt; accepts skill IDs or paths to skill directories (`/`, `~/`, `./`, `../`) | `aia -s code-quality my_prompt` or `aia -s ~/skills/my-skill` |
+| `--list-skills` | List available skills and exit | `aia --list-skills` |
+| `--skills-dir DIR` | Set skills directory (default: `~/.prompts/skills`) | `aia --skills-dir ~/skills` |
 | `--output FILE` | Specify output file | `aia --output results.md` |
 | `--fuzzy` | Use fuzzy search for prompts | `aia --fuzzy` |
 | `--tokens` | Display token usage in chat mode | `aia --chat --tokens` |
@@ -283,6 +388,11 @@ aia --fuzzy
 ├── roles/              # Role/system prompts
 │   ├── expert.md       # Expert role
 │   └── teacher.md      # Teaching role
+├── skills/             # Skill directories
+│   ├── code-quality/   # Skill subdirectory
+│   │   └── SKILL.md   # Skill definition (YAML front matter + content)
+│   └── summarizer/
+│       └── SKILL.md
 └── _prompts.log        # History log
 ```
 
@@ -307,8 +417,10 @@ AIA determines configuration settings using this order (highest to lowest priori
 1. **Embedded config directives** (in prompt files): `/config model = gpt-4`
 2. **Command-line arguments**: `--model gpt-4`
 3. **Environment variables**: `export AIA_MODEL=gpt-4`
-4. **Configuration files**: `~/.aia/config.yml`
-5. **Default values**
+4. **Configuration files**: `~/.config/aia/aia.yml`
+5. **Default values**: [defaults.yml](lib/aia/config/defaults.yml)
+
+**Note:** When `-c` / `--config-file` is used, it replaces the user config and environment variables. Configuration resets to bundled defaults, then the specified file is applied, then CLI arguments take precedence.
 
 ### Configuration Methods
 
@@ -319,12 +431,16 @@ export AIA_PROMPTS__DIR=~/my-prompts
 export AIA_LLM__TEMPERATURE=0.8
 ```
 
-**Configuration File** (`~/.aia/config.yml`):
+**Configuration File** (`~/.config/aia/aia.yml`):
 ```yaml
-model: gpt-4
-prompts_dir: ~/my-prompts
-temperature: 0.8
-chat: false
+models:
+  - name: gpt-4
+prompts:
+  dir: ~/my-prompts
+llm:
+  temperature: 0.8
+flags:
+  chat: false
 ```
 
 **Embedded Directives** (in prompt files):
@@ -340,56 +456,113 @@ Your prompt content here...
 <details>
 <summary>Click to view all configuration options</summary>
 
-| Config Item Name | CLI Options | Default Value | Environment Variable |
-|------------------|-------------|---------------|---------------------|
-| adapter | --adapter | ruby_llm | AIA_ADAPTER |
-| aia_dir | | ~/.aia | AIA_DIR |
-| append | -a, --append | false | AIA_FLAGS__APPEND |
-| chat | --chat | false | AIA_FLAGS__CHAT |
-| clear | --clear | false | AIA_FLAGS__CLEAR |
-| config_file | -c, --config-file | ~/.aia/config.yml | AIA_CONFIG_FILE |
-| debug | -d, --debug | false | AIA_FLAGS__DEBUG |
-| embedding_model | --em, --embedding_model | text-embedding-ada-002 | AIA_LLM__EMBEDDING_MODEL |
-| erb | | true | AIA_FLAGS__ERB |
-| frequency_penalty | --frequency-penalty | 0.0 | AIA_LLM__FREQUENCY_PENALTY |
-| fuzzy | -f, --fuzzy | false | AIA_FLAGS__FUZZY |
-| image_quality | --iq, --image-quality | standard | AIA_IMAGE__QUALITY |
-| image_size | --is, --image-size | 1024x1024 | AIA_IMAGE__SIZE |
-| image_style | --style, --image-style | vivid | AIA_IMAGE__STYLE |
-| history_file | --history-file | ~/.prompts/_prompts.log | AIA_OUTPUT__HISTORY_FILE |
-| markdown | --md, --markdown | true | AIA_OUTPUT__MARKDOWN |
-| max_tokens | --max-tokens | 2048 | AIA_LLM__MAX_TOKENS |
-| model | -m, --model | gpt-4o-mini | AIA_MODEL |
-| next | -n, --next | nil | AIA_NEXT |
-| output | -o, --output | temp.md | AIA_OUTPUT__FILE |
-| parameter_regex | --regex | '(?-mix:(\[[A-Z _\|]+\]))' | AIA_PROMPTS__PARAMETER_REGEX |
-| pipeline | --pipeline | [] | AIA_PIPELINE |
-| presence_penalty | --presence-penalty | 0.0 | AIA_LLM__PRESENCE_PENALTY |
-| prompt_extname | | .md | AIA_PROMPTS__EXTNAME |
-| prompts_dir | --prompts-dir | ~/.prompts | AIA_PROMPTS__DIR |
-| refresh | --refresh | 7 (days) | AIA_REGISTRY__REFRESH |
-| require_libs | --rq --require | [] | AIA_REQUIRE_LIBS |
-| role | -r, --role | | AIA_ROLE |
-| roles_dir | | ~/.prompts/roles | AIA_ROLES__DIR |
-| roles_prefix | --roles-prefix | roles | AIA_ROLES__PREFIX |
-| shell | | true | AIA_FLAGS__SHELL |
-| speak | --speak | false | AIA_FLAGS__SPEAK |
-| speak_command | | afplay | AIA_SPEECH__COMMAND |
-| speech_model | --sm, --speech-model | tts-1 | AIA_SPEECH__MODEL |
-| system_prompt | --system-prompt | | AIA_SYSTEM_PROMPT |
-| temperature | -t, --temperature | 0.7 | AIA_LLM__TEMPERATURE |
-| terse | --terse | false | AIA_FLAGS__TERSE |
-| tokens | --tokens | false | AIA_FLAGS__TOKENS |
-| cost | --cost | false | AIA_FLAGS__COST |
-| tool_paths | --tools | [] | AIA_TOOLS__PATHS |
-| allowed_tools | --at, --allowed-tools | nil | AIA_TOOLS__ALLOWED |
-| rejected_tools | --rt, --rejected-tools | nil | AIA_TOOLS__REJECTED |
-| mcp_use | --mu, --mcp-use | ~ | AIA_MCP_USE |
-| mcp_skip | --ms, --mcp-skip | ~ | AIA_MCP_SKIP |
-| top_p | --top-p | 1.0 | AIA_LLM__TOP_P |
-| transcription_model | --tm, --transcription-model | whisper-1 | AIA_TRANSCRIPTION__MODEL |
-| verbose | -v, --verbose | false | AIA_FLAGS__VERBOSE |
-| voice | --voice | alloy | AIA_SPEECH__VOICE |
+The configuration schema is defined in [defaults.yml](lib/aia/config/defaults.yml). Environment variables use the `AIA_` prefix with double underscores for nested keys.
+
+**Mode & Display Flags:**
+
+| Config Path | CLI Options | Default | Environment Variable |
+|-------------|-------------|---------|---------------------|
+| `flags.chat` | `--chat` | `false` | `AIA_FLAGS__CHAT` |
+| `flags.fuzzy` | `-f`, `--fuzzy` | `false` | `AIA_FLAGS__FUZZY` |
+| `flags.debug` | `-d`, `--debug` | `false` | `AIA_FLAGS__DEBUG` |
+| `flags.verbose` | `-v`, `--verbose` | `false` | `AIA_FLAGS__VERBOSE` |
+| `flags.tokens` | `--tokens` | `false` | `AIA_FLAGS__TOKENS` |
+| `flags.cost` | `--cost` | `false` | `AIA_FLAGS__COST` |
+| `flags.consensus` | `--[no-]consensus` | `false` | `AIA_FLAGS__CONSENSUS` |
+| `flags.speak` | `--speak` | `false` | `AIA_FLAGS__SPEAK` |
+| `flags.shell` | | `true` | `AIA_FLAGS__SHELL` |
+| `flags.erb` | | `true` | `AIA_FLAGS__ERB` |
+| `flags.clear` | `--clear` | `false` | `AIA_FLAGS__CLEAR` |
+| `flags.no_mcp` | `--no-mcp` | `false` | `AIA_FLAGS__NO_MCP` |
+
+**Model & LLM Parameters:**
+
+| Config Path | CLI Options | Default | Environment Variable |
+|-------------|-------------|---------|---------------------|
+| `models` | `-m`, `--model` | `gpt-4o-mini` | `AIA_MODEL` |
+| `llm.temperature` | `-t`, `--temperature` | `0.7` | `AIA_LLM__TEMPERATURE` |
+| `llm.max_tokens` | `--max-tokens` | `2048` | `AIA_LLM__MAX_TOKENS` |
+| `llm.top_p` | `--top-p` | `1.0` | `AIA_LLM__TOP_P` |
+| `llm.frequency_penalty` | `--frequency-penalty` | `0.0` | `AIA_LLM__FREQUENCY_PENALTY` |
+| `llm.presence_penalty` | `--presence-penalty` | `0.0` | `AIA_LLM__PRESENCE_PENALTY` |
+
+**Prompts, Roles & Skills:**
+
+| Config Path | CLI Options | Default | Environment Variable |
+|-------------|-------------|---------|---------------------|
+| `prompts.dir` | `--prompts-dir` | `~/.prompts` | `AIA_PROMPTS__DIR` |
+| `prompts.extname` | | `.md` | `AIA_PROMPTS__EXTNAME` |
+| `prompts.roles_prefix` | `--roles-prefix` | `roles` | `AIA_PROMPTS__ROLES_PREFIX` |
+| `prompts.roles_dir` | | `~/.prompts/roles` | `AIA_PROMPTS__ROLES_DIR` |
+| `prompts.role` | `-r`, `--role` | | `AIA_PROMPTS__ROLE` |
+| `prompts.skills` | `-s`, `--skill` | `[]` | |
+| `prompts.skills_prefix` | `--skills-prefix` | `skills` | `AIA_PROMPTS__SKILLS_PREFIX` |
+| `skills.dir` | `--skills-dir` | `~/.prompts/skills` | `AIA_SKILLS__DIR` |
+| `prompts.system_prompt` | `--system-prompt` | | `AIA_PROMPTS__SYSTEM_PROMPT` |
+| `pipeline` | `-p`, `--pipeline` | `[]` | |
+| | `-n`, `--next` | | |
+
+**Output & Files:**
+
+| Config Path | CLI Options | Default | Environment Variable |
+|-------------|-------------|---------|---------------------|
+| `output.file` | `-o`, `--[no-]output` | `temp.md` | `AIA_OUTPUT__FILE` |
+| `output.append` | `-a`, `--[no-]append` | `false` | `AIA_OUTPUT__APPEND` |
+| `output.markdown` | `--md`, `--[no-]markdown` | `true` | `AIA_OUTPUT__MARKDOWN` |
+| `output.history_file` | `--history-file` | `~/.prompts/_prompts.log` | `AIA_OUTPUT__HISTORY_FILE` |
+| `paths.aia_dir` | | `~/.config/aia` | `AIA_PATHS__AIA_DIR` |
+| `paths.config_file` | `-c`, `--config-file` | `~/.config/aia/aia.yml` | `AIA_PATHS__CONFIG_FILE` |
+
+**Audio & Image:**
+
+| Config Path | CLI Options | Default | Environment Variable |
+|-------------|-------------|---------|---------------------|
+| `audio.voice` | `--voice` | `alloy` | `AIA_AUDIO__VOICE` |
+| `audio.speak_command` | | `afplay` | `AIA_AUDIO__SPEAK_COMMAND` |
+| `audio.speech_model` | `--sm`, `--speech-model` | `tts-1` | `AIA_AUDIO__SPEECH_MODEL` |
+| `audio.transcription_model` | `--tm`, `--transcription-model` | `whisper-1` | `AIA_AUDIO__TRANSCRIPTION_MODEL` |
+| `image.size` | `--is`, `--image-size` | `1024x1024` | `AIA_IMAGE__SIZE` |
+| `image.quality` | `--iq`, `--image-quality` | `standard` | `AIA_IMAGE__QUALITY` |
+| `image.style` | `--style`, `--image-style` | `vivid` | `AIA_IMAGE__STYLE` |
+| `embedding.model` | | `text-embedding-ada-002` | `AIA_EMBEDDING__MODEL` |
+
+**Tools & MCP:**
+
+| Config Path | CLI Options | Default | Environment Variable |
+|-------------|-------------|---------|---------------------|
+| `tools.paths` | `--tools` | `[]` | `AIA_TOOLS__PATHS` |
+| `tools.allowed` | `--at`, `--allowed-tools` | | `AIA_TOOLS__ALLOWED` |
+| `tools.rejected` | `--rt`, `--rejected-tools` | | `AIA_TOOLS__REJECTED` |
+| `mcp_servers` | | `[]` | |
+| `mcp_use` | `--mu`, `--mcp-use` | | `AIA_MCP_USE` |
+| `mcp_skip` | `--ms`, `--mcp-skip` | | `AIA_MCP_SKIP` |
+| | `--mcp FILE` | | |
+| | `--mcp-list` | | |
+| `require_libs` | `--rq`, `--require` | `[]` | |
+
+**Logging:**
+
+| Config Path | CLI Options | Default | Environment Variable |
+|-------------|-------------|---------|---------------------|
+| `logger.aia.level` | `--log-level` | `warn` | `AIA_LOGGER__AIA__LEVEL` |
+| `logger.aia.file` | `--log-to` | `STDOUT` | `AIA_LOGGER__AIA__FILE` |
+| `logger.llm.level` | `--log-level` | `warn` | `AIA_LOGGER__LLM__LEVEL` |
+| `logger.llm.file` | `--log-to` | `STDOUT` | `AIA_LOGGER__LLM__FILE` |
+| `logger.mcp.level` | `--log-level` | `warn` | `AIA_LOGGER__MCP__LEVEL` |
+| `logger.mcp.file` | `--log-to` | `STDOUT` | `AIA_LOGGER__MCP__FILE` |
+| `registry.refresh` | `--refresh` | `7` (days) | `AIA_REGISTRY__REFRESH` |
+
+**Utility:**
+
+| CLI Options | Description |
+|-------------|-------------|
+| `--dump FILE` | Export current configuration to FILE and exit |
+| `--completion SHELL` | Generate shell completion script (bash/zsh/fish) and exit |
+| `--available-models [QUERY]` | List available models and exit |
+| `--list-roles` | List available role files and exit |
+| `--list-tools` | List available tools and exit |
+| `--version` | Show version and exit |
+| `-h`, `--help` | Show help and exit |
 
 </details>
 
@@ -407,6 +580,8 @@ Directives are special commands in prompt files that begin with `/` and provide
 | `/restore` | Restore context to a previous checkpoint | `/restore save_point` |
 | `/include` | Insert file contents | `/include path/to/file.txt` |
 | `/paste` | Insert clipboard contents | `/paste` |
+| `/skill` | Include a skill by ID or path to a skill directory | `/skill code-quality` or `/skill ~/skills/my-skill` |
+| `/skills` | List available Claude Code skills | `/skills` |
 | `/shell` | Execute shell commands | `/shell ls -la` |
 | `/robot` | Show the pet robot ASCII art w/versions | `/robot` |
 | `/ruby` | Execute Ruby code | `/ruby puts "Hello World"` |
@@ -513,29 +688,29 @@ Checkpoints: ruby_basics, oop_concepts
 
 #### Custom Directive Examples
 
-You can extend AIA with custom directives by creating Ruby files that define new directive methods:
+You can extend AIA with custom directives by subclassing `AIA::Directive`. Use `desc` before a method to register it as a directive. Aliases are detected automatically via `alias_method`.
 
 ```ruby
-# examples/directives/ask.rb
+# examples/directives/timestamp_directive.rb
 module AIA
-  class DirectiveProcessor
-    private
-    desc "A meta-prompt to LLM making its response available as part of the primary prompt"
-    def ask(args, context_manager=nil)
-      meta_prompt = args.empty? ? "What is meta-prompting?" : args.join(' ')
-      AIA.config.client.chat(meta_prompt)
+  class CustomDirectives < Directive
+    desc "Insert current timestamp (optional strftime format, default: %Y-%m-%d %H:%M:%S)"
+    def timestamp(args = [], context_manager = nil)
+      format = args.empty? ? '%Y-%m-%d %H:%M:%S' : args.join(' ')
+      Time.now.strftime(format)
     end
   end
 end
 ```
 
-**Usage:** Use the --tools option to specific a specific directive file or a directory full of files
+**Usage:** Use the `--tools` option to load a directive file or a directory of files:
 ```bash
 # Load custom directive
-aia --tools examples/directives/ask.rb --chat
+aia --tools examples/directives/timestamp_directive.rb --chat
 
-# Use the results of the custom directive as input to a prompt
-/ask gather the latest closing data for the DOW, NASDAQ, and S&P 500
+# Use the custom directive in chat mode
+/timestamp
+/timestamp %Y-%m-%d
 ```
 
 ### Multi-Model Support
@@ -934,25 +1109,40 @@ echo "You are a senior software architect..." > ~/.prompts/roles/specialized/sen
 aia --model gpt-4o=specialized/senior_architect design.md
 ```
 
-**Using Config Files for Model Roles** (v2):
+**Path-Based Roles:**
+
+In addition to role IDs looked up under `~/.prompts/roles/`, you can pass a direct filesystem path as the role. Any value starting with `/`, `~/`, `./`, or `../` is treated as a path rather than an ID. The `.md` extension is appended automatically when the path has none.
+
+```bash
+# Absolute path
+aia --role /team/shared/roles/senior_engineer.md my_prompt
+
+# Home-relative path (~ expanded)
+aia --role ~/custom/roles/reviewer my_prompt   # loads ~/custom/roles/reviewer.md
+
+# Relative path
+aia --role ./local_role my_prompt              # loads ./local_role.md
+```
+
+**Using Config Files for Model Roles:**
 
-Define model-role assignments in your config file (`~/.aia/config.yml`) for reusable setups:
+Define model-role assignments in your config file (`~/.config/aia/aia.yml`) for reusable setups:
 
 ```yaml
 # Array of hashes format (mirrors internal structure)
-model:
-  - model: gpt-4o
+models:
+  - name: gpt-4o
     role: architect
-  - model: claude
+  - name: claude
     role: security
-  - model: gemini
+  - name: gemini
     role: performance
 
 # Also supports models without roles
-model:
-  - model: gpt-4o
+models:
+  - name: gpt-4o
     role: architect
-  - model: claude      # No role assigned
+  - name: claude      # No role assigned
 ```
 
 Then simply run:
@@ -961,7 +1151,7 @@ Then simply run:
 aia design_doc.md  # Uses model configuration from config file
 ```
 
-**Using Environment Variables** (v2):
+**Using Environment Variables:**
 
 Set default model-role assignments via environment variable:
 
@@ -980,9 +1170,37 @@ When model roles are specified in multiple places, the precedence is:
 1. **Command-line inline** (highest): `--model gpt-4o=architect`
 2. **Command-line flag**: `--model gpt-4o --role architect`
 3. **Environment variable**: `AIA_MODEL="gpt-4o=architect"`
-4. **Config file** (lowest): `model` array in `~/.aia/config.yml`
+4. **Config file** (lowest): `models` array in `~/.config/aia/aia.yml`
+
+### Skills
+
+Skills are reusable instruction sets prepended to prompts. Each skill is a directory containing a `SKILL.md` file with YAML front matter and content.
+
+```bash
+# Use a skill by ID (looked up under skills.dir, default ~/.prompts/skills)
+aia -s code-quality my_prompt
+
+# Comma-separated for multiple skills
+aia -s code-quality,security-review my_prompt
+
+# Path-based: pass a direct path to a skill directory
+aia -s ~/team/skills/my-skill my_prompt     # home-relative
+aia -s /shared/skills/company-style prompt  # absolute path
+aia -s ./local-skill my_prompt              # relative path
+
+# List available skills
+aia --list-skills
 ```
 
+Skills can also be applied during chat via the `/skill` directive:
+
+```
+/skill code-quality
+/skill ~/team/skills/my-skill
+```
+
+Path-based values (starting with `/`, `~/`, `./`, or `../`) are resolved as filesystem paths to skill directories directly, bypassing the configured skills directory lookup.
+
 ### RubyLLM::Tool Support
 
 AIA supports function calling through RubyLLM tools for extended capabilities:
@@ -1023,14 +1241,14 @@ These MCP clients require the `ruby_llm-mcp` gem and provide access to external
 
 ### MCP Server Configuration
 
-AIA supports defining MCP (Model Context Protocol) servers directly in your configuration file. This allows MCP tools to be automatically loaded at startup without needing to specify them on the command line each time.
+AIA supports defining MCP (Model Context Protocol) servers directly in your configuration file. This allows MCP tools to be automatically loaded at startup without needing to specify them on the command line each time. When multiple MCP servers are configured, AIA connects to them **in parallel** using fiber-based concurrency (via the `simple_flow` gem) for faster startup.
 
 #### Configuration Format
 
-Add MCP servers to your `~/.aia/config.yml` file:
+Add MCP servers to your `~/.config/aia/aia.yml` file:
 
 ```yaml
-:mcp_servers:
+mcp_servers:
   - name: "server-name"
     command: "server_command"
     args: ["arg1", "arg2"]
@@ -1054,8 +1272,8 @@ Add MCP servers to your `~/.aia/config.yml` file:
 The GitHub MCP server provides access to GitHub repositories, issues, pull requests, and more:
 
 ```yaml
-# ~/.aia/config.yml
-:mcp_servers:
+# ~/.config/aia/aia.yml
+mcp_servers:
   - name: "github"
     command: "github-mcp-server"
     args: ["stdio"]
@@ -1087,8 +1305,8 @@ See the [full HTM documentation](https://madbomber.github.io/htm) for database c
 A custom Ruby-based MCP server for accessing database-backed long term memory:
 
 ```yaml
-# ~/.aia/config.yml
-:mcp_servers:
+# ~/.config/aia/aia.yml
+mcp_servers:
   - name: "htm"
     command: "htm_mcp.rb"
     args: ["stdio"]
@@ -1108,8 +1326,8 @@ A custom Ruby-based MCP server for accessing database-backed long term memory:
 You can configure multiple MCP servers to provide different capabilities:
 
 ```yaml
-# ~/.aia/config.yml
-:mcp_servers:
+# ~/.config/aia/aia.yml
+mcp_servers:
   - name: "github"
     command: "github-mcp-server"
     args: ["stdio"]
@@ -1134,11 +1352,11 @@ When MCP servers are configured, AIA displays them in the startup robot:
 
 ```
        ,      ,
-       (\____/) AI Assistant (v0.9.23) is Online
+       (\____/) AI Assistant (v1.1.0) is Online
         (_oo_)   gpt-4o-mini (supports tools)
-         (O)       using ruby_llm (v1.9.0 MCP v0.6.1)
+         (O)       using ruby_llm
        __||__    \) model db was last refreshed on
-     [/______\]  /    2025-06-03
+     [/______\]  /    2025-06-18
     / \__AI__/ \/      You can share my tools
    /    /__\              MCP: github, htm
   (\   /____\
@@ -1415,11 +1633,11 @@ echo "Home: $HOME"    # Should show home directory
 
 **Configuration issues:**
 ```bash
-# Check current configuration
-aia --config
+# Dump current configuration to a file
+aia --dump config_snapshot.yml
 
 # Debug configuration loading
-aia --debug --config
+aia --debug my_prompt
 ```
 
 ### Error Messages
@@ -1553,7 +1771,6 @@ rake test
 
 - **Enhanced Search**: Restore full-text search within prompt files
 - **UI Improvements**: Better configuration management for fzf and rg tools
-- **Logging**: Enhanced logging using Ruby Logger class; integration with RubyLLM and RubyLLM::MCP logging
 
 ## License