aia 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93f948db1a8860374c1c8d5e5913fc6f53c41d827fb9f5f4cbac546c9d5029da
-  data.tar.gz: dd3300150ace0fff6103f6fac3571cd2b782b57ca485e6aee264a5d1eb0a59e0
+  metadata.gz: d72af72c970719f5d9508d14fc7903e46b7b751028d75cb045c8c23418151b44
+  data.tar.gz: 7a2b43f842f38d7e2f94f2118c85f087a4f97b944958b7a63c5d2798bab05cb9
 SHA512:
-  metadata.gz: 9312d50d65c8e9952a5762796989cd925691f0da38aaa4b9839af1438c2cf43b3256c884668956e77de6917f8cefdcb5e006c85dd94645ff226a7eb154d10b1b
-  data.tar.gz: a20827ca6d36ed203fc9d322ae7d6593f0696d7e48d5378291968f99c75abddb52f0c71dda349db4c86c6c08ac47a8cb0dddac7a3f70d68bc201b2778ea96511
+  metadata.gz: a27344680f0eb4ac9f1a9535982b53b102bb2face18b66f293918996a9b27e6d29aea2c46480671c2abecbb9a7e4f8c1400c84d5f157f7083c357a8766b399da
+  data.tar.gz: 3b740188dc4b8a74873fca77112fde35737574bd47c2a2c7f3e888cc831b669fb520b3e5e212b6124960ca0afe09ebe5fa004bf8e18f8507e32f5ea58afb5ae5

data/.version

@@ -1 +1 @@
-1.0.0
+1.1.0

data/CHANGELOG.md

@@ -1,4 +1,55 @@
 # Changelog
+## [1.1.0] - 2026-04-23
+
+### New Features
+- **Skills system**: Skills are subdirectories under `~/.prompts/skills` (configurable), each containing a `SKILL.md` file with YAML front matter (`name`, `description`, and any custom fields)
+  - `/skills [query]` directive lists available skills; supports positive/negative search filtering (`-term`, `~term`, `!term`)
+  - `/skill <name>` directive includes the `SKILL.md` content into the conversation; resolves by exact match then prefix match
+  - `/skill <path>` directive accepts path-based IDs (absolute, `~/`, `./`, `../`) including direct `.md` files
+  - `--list-skills` CLI flag prints all skills as markdown tables (one `## skill` heading + `| Key | Value |` table per skill, showing all front matter fields)
+  - `--skill`/`-s SKILL_IDS` CLI option prepends one or more skills to the prompt (comma-separated, repeatable); accepts skill IDs or paths
+  - `--skills-dir DIR` and `--skills-prefix PREFIX` CLI options configure the skills directory
+- **Path-based skill resolution**: `--skill` and `/skill` now accept file-system paths in addition to named IDs
+  - Absolute paths: `--skill /path/to/skill-dir` or `--skill /path/to/skill.md`
+  - Home-relative: `--skill ~/skills/my-skill`
+  - Working-directory-relative: `--skill ./temp_skill.md`
+  - Direct `.md` files: the file content is used as-is (front matter stripped); no `SKILL.md` lookup needed
+- **Path-based role resolution**: `--role` now accepts file-system paths in addition to role IDs
+  - Absolute and home-relative paths bypass the `~/.prompts/roles/` prefix lookup
+  - Example: `aia --role ~/custom/expert.md my_prompt`
+- **Skills in chat-only mode**: `ChatLoop` now loads and sends configured skills to the AI at session start via `process_skill_context`, even when no pipeline prompt is specified; the AI's acknowledgment is displayed so the user can confirm the skill was applied
+- **`AIA::SkillUtils` module**: New shared utility module (`lib/aia/skill_utils.rb`) consolidating path and skill helpers previously duplicated across four classes
+  - `path_based_id?(id)` — detects `/`, `~/`, `./`, `../` prefixes
+  - `parse_front_matter(path)` — reads and parses YAML front matter from a `.md` file; returns `{}` on any failure
+  - `find_skill_dir(skill_name, base_dir)` — resolves a skill name or path to its directory (or direct `.md` file); enforces symlink/prefix-traversal checks for ID-based lookups
+  - `safe_skill_path(path, dir)` — verifies a resolved path is contained within `dir` using `File::SEPARATOR`-terminated prefix to prevent sibling-directory attacks
+  - `skill_body(content)` — strips YAML front matter from skill file content
+  - Included by `PromptPipeline`, `PromptHandler`, `WebAndFileDirectives`, `CLIParser`, `ConfigValidator`, and `ChatLoop`
+- **`roles` config section**: Top-level `roles.dir` config key (`~/.prompts/roles` default) alongside existing `prompts.roles_prefix`
+- **`parse_search_terms` helper**: New private method on `AIA::Directive` base class available to all directive subclasses; splits argument tokens into `[positive_terms, negative_terms]` arrays (negative prefixes: `-`, `~`, `!`; positive: `+` or bare; all downcased)
+
+### Bug Fixes
+- **Direct `.md` skill files silently ignored**: `--skill ./my-skill.md` previously returned `nil` because `find_skill_dir` only checked `Dir.exist?`. Now checks `File.file?` and returns the path directly; `load_skills` and `/skill` read and strip front matter from the file without requiring a `SKILL.md` sub-file
+- **Path-prefix collision in `safe_skill_path`**: A sibling directory named `skills-attack` could bypass the containment check against `skills` because `start_with?(realpath)` matched the shared prefix. Fixed by appending `File::SEPARATOR` to the base path before the `start_with?` comparison
+- **Path-based role IDs incorrectly prefixed**: `ConfigValidator#process_role_configuration` was unconditionally prepending the roles prefix (e.g., `roles/`) to role IDs, corrupting absolute and relative paths like `/custom/role.md` into `roles//custom/role.md`. Now guards with `AIA::SkillUtils.path_based_id?` before applying the prefix
+
+### Improvements
+- **`/available_models` filtering** now uses `parse_search_terms` for consistent positive/negative term filtering across local (Ollama, LM Studio) and cloud model listings
+- **Standardized warning output**: Replaced `$stderr.puts` with `warn` throughout `prompt_pipeline.rb` for idiomatic Ruby error reporting
+- **Skills CLI options moved to Prompt Options group**: `--skill`, `--skills-dir`, `--skills-prefix`, `--list-skills` now appear under `--help`'s Prompt Options section alongside `--role` and related options, rather than Model Options
+
+### Testing
+- Added `test/aia/skill_utils_test.rb` — 24 tests covering all `AIA::SkillUtils` methods including symlink traversal blocking, sibling-prefix collision, direct `.md` file resolution, and nonexistent path handling
+- Added `test/aia/config/cli_parser_skills_test.rb` — 8 tests covering all skills-related CLI options
+- Added `test/aia/config/skills_config_test.rb` — 8 tests covering skills config defaults and overrides
+- Added `test/aia/directive_search_terms_test.rb` — 10 tests covering all `parse_search_terms` token forms
+- Expanded `test/aia/directives/skill_directive_test.rb` with path-based, direct-file, security (path traversal, symlink), and edge-case coverage (36 tests total)
+- Added `test/aia/prompt_pipeline_skills_test.rb` — pipeline-level skill loading tests including absolute paths, direct `.md` files, warning capture via Mocha stubs, and mixed path+ID loading (6 tests)
+- Added `test/aia/session_test.rb` `ChatLoopTest` entries for `process_skill_context` — noop when no skills configured, sends skill content to processor when configured (2 tests)
+- Eliminated `Dir.chdir` side effects from 3 tests (`skill_directive_test.rb`, `prompt_pipeline_skills_test.rb`, `prompt_handler_role_path_test.rb`) that used it to simulate relative-path resolution; replaced with absolute-path construction
+- Updated 2 pipeline warning tests to use Mocha's `.stubs(:warn).with { }` argument-matcher pattern instead of `capture_io` (which cannot intercept `warn` when `$stderr` is reassigned in Ruby 4.0)
+- Full test suite: 925 runs, 0 failures, 0 errors, 0 skips
+
 ## [1.0.0] - 2026-02-22
 
 ### Security Fixes

data/README.md

@@ -7,17 +7,11 @@
 
 ---
 
-<details>
-<summary><strong>Upgrading from v0.x?</strong> Click to see migration notes.</summary>
-
-- **Prompt files** now use `.md` extension. Run `bin/migrate_prompts ~/.prompts` to convert existing prompts.
-- **Environment variables** use double underscore (`__`) for nested config sections (e.g., `AIA_LLM__TEMPERATURE`, `AIA_FLAGS__DEBUG`).
-- **Configuration files** use a nested YAML structure with sections like `llm:`, `prompts:`, `output:`, `flags:`, etc. See [defaults.yml](lib/aia/config/defaults.yml) for the complete schema.
-- **File locations** follow the XDG Base Directory Specification. Config file is now at `~/.config/aia/aia.yml`.
-
-See the [Configuration Guide](https://madbomber.github.io/aia/configuration/) for details.
+> ### 🚀 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)**
 
-</details>
+---
 
 ---
 
@@ -70,7 +64,7 @@ For more information on AIA visit these locations:
 ```plain
 
        ,      ,
-       (\____/) AI Assistant (v1.0.0) is Online
+       (\____/) AI Assistant (v1.1.0) is Online
         (_oo_)   gpt-4o-mini
          (O)       using ruby_llm
        __||__    \) model db was last refreshed on
@@ -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
 ```
 
@@ -376,7 +486,7 @@ The configuration schema is defined in [defaults.yml](lib/aia/config/defaults.ym
 | `llm.frequency_penalty` | `--frequency-penalty` | `0.0` | `AIA_LLM__FREQUENCY_PENALTY` |
 | `llm.presence_penalty` | `--presence-penalty` | `0.0` | `AIA_LLM__PRESENCE_PENALTY` |
 
-**Prompts & Roles:**
+**Prompts, Roles & Skills:**
 
 | Config Path | CLI Options | Default | Environment Variable |
 |-------------|-------------|---------|---------------------|
@@ -385,6 +495,9 @@ The configuration schema is defined in [defaults.yml](lib/aia/config/defaults.ym
 | `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` | | |
@@ -467,7 +580,7 @@ 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 Claude Code skill | `/skill code-quality` |
+| `/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` |
@@ -996,6 +1109,21 @@ echo "You are a senior software architect..." > ~/.prompts/roles/specialized/sen
 aia --model gpt-4o=specialized/senior_architect design.md
 ```
 
+**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 (`~/.config/aia/aia.yml`) for reusable setups:
@@ -1044,6 +1172,35 @@ When model roles are specified in multiple places, the precedence is:
 3. **Environment variable**: `AIA_MODEL="gpt-4o=architect"`
 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:
@@ -1195,7 +1352,7 @@ When MCP servers are configured, AIA displays them in the startup robot:
 
 ```
        ,      ,
-       (\____/) AI Assistant (v1.0.0) is Online
+       (\____/) AI Assistant (v1.1.0) is Online
         (_oo_)   gpt-4o-mini (supports tools)
          (O)       using ruby_llm
        __||__    \) model db was last refreshed on

data/docs/cli-reference.md

@@ -236,6 +236,90 @@ aia --model "gpt-4,claude-3-sonnet" --consensus my_prompt
 aia --model "gpt-4,claude-3-sonnet" --no-consensus my_prompt
 ```
 
+### `-s, --skill SKILL_IDS`
+Inject one or more skills into the prompt before it is sent to the AI. Skills are loaded from the skills directory (default: `~/.prompts/skills/`). Multiple skills can be specified as a comma-separated list, and the flag may be repeated.
+
+Skills are inserted **after the role and before the user prompt**, providing task-level instructions for how the LLM should approach the request:
+
+```
+Role content  (who the LLM is)
+Skill content (how to approach the task)
+User prompt   (what to do)
+```
+
+Only the body of each `SKILL.md` is injected — the YAML front matter is stripped.
+
+```bash
+# Single skill (ID-based — resolved from skills directory)
+aia --skill code-review my_prompt
+aia -s summarizer my_prompt
+
+# Path-based skill (relative, home-relative, or absolute path to a skill directory)
+aia --skill ./local-skills/code-review my_prompt
+aia --skill /shared/team-skills/security-audit my_prompt
+aia --skill ~/my-skills/custom-skill my_prompt
+
+# Combine with a role: role sets persona, skill sets method
+aia --role ruby_expert --skill code-review review_prompt my_code.rb
+
+# Multiple skills applied in order (comma-separated)
+aia --skill "code-review,security-audit" my_prompt
+
+# Repeatable form
+aia -s code-review -s security-audit my_prompt
+```
+
+**Path resolution**: If a skill ID starts with `/`, `~/`, `./`, or `../`, it is treated as a filesystem path to a skill directory (which must contain `SKILL.md`). Otherwise it is looked up by ID in the skills directory.
+
+**See also**: `--list-skills` to discover available skills, `/skill` chat directive, `--role` for personality
+
+### `--list-skills`
+List all available skills and exit. Skills are subdirectories under the skills directory, each containing a `SKILL.md` file with YAML front matter.
+
+```bash
+aia --list-skills
+
+# With a custom skills directory
+aia --skills-dir ~/work/skills --list-skills
+```
+
+**Example output**:
+```markdown
+## code-quality
+
+| Key | Value |
+|-----|-------|
+| name | code-quality |
+| description | Improve code quality through analysis and refactoring. |
+| user-invocable | true |
+
+## summarizer
+
+| Key | Value |
+|-----|-------|
+| name | summarizer |
+| description | Summarize documents and conversations concisely. |
+```
+
+Each skill is shown as a `## skill-name` heading followed by a table of all front matter fields from its `SKILL.md`.
+
+### `--skills-dir DIR`
+Directory containing skill subdirectories (default: `~/.prompts/skills`). Each subdirectory must contain a `SKILL.md` file to be recognized as a skill.
+
+```bash
+aia --skills-dir ~/work/skills --list-skills
+aia --skills-dir /shared/team-skills -s code-review my_prompt
+```
+
+**Environment variable**: `AIA_SKILLS__DIR`
+
+### `--skills-prefix PREFIX`
+Subdirectory name within `--prompts-dir` used as the skills prefix (default: `skills`). Affects `AIA.config.prompts.skills_prefix`.
+
+```bash
+aia --skills-prefix team-skills --list-skills
+```
+
 ### `--sm, --speech-model MODEL`
 Speech model to use for text-to-speech functionality.
 
@@ -341,10 +425,15 @@ Role ID to prepend to the prompt. This applies the same role to all models.
 For per-model role assignment, use the inline `MODEL=ROLE` syntax with `--model` instead.
 
 ```bash
-# Apply role to all models
+# Apply role by ID (resolved from roles directory)
 aia --role expert my_prompt
 aia -r teacher explain_concept
 
+# Path-based role (relative or absolute path to a .md file)
+aia --role ./local-roles/domain-expert my_prompt
+aia --role /shared/roles/security-auditor review.md
+aia --role ~/my-roles/custom-persona my_prompt
+
 # With multiple models (same role for all)
 aia --model "gpt-4,claude" --role architect design.md
 
@@ -352,6 +441,8 @@ aia --model "gpt-4,claude" --role architect design.md
 aia --model "gpt-4=architect,claude=security" design.md
 ```
 
+**Path resolution**: If `ROLE_ID` starts with `/`, `~/`, `./`, or `../`, it is treated as a filesystem path to a role `.md` file. The `.md` extension is added automatically when the path has no file extension. Otherwise the ID is resolved relative to the roles directory.
+
 **See also**: `--model` for inline role syntax, `--list-roles` for discovering available roles.
 
 ### `--list-roles`

data/docs/configuration.md

@@ -53,9 +53,27 @@ prompts:
   roles_prefix: roles         # Subdirectory name for role files
   roles_dir: ~/.prompts/roles # Full path to roles directory
   role: ~                     # Default role
+  skills: []                  # Skill IDs to prepend to prompt (set by --skill/-s)
+  skills_prefix: skills       # Subdirectory name for skill directories
   system_prompt: ~            # Default system prompt
   parameter_regex: ~          # Regex for parameter extraction
 
+# Roles Configuration
+# Access: AIA.config.roles.dir
+# Env: AIA_ROLES__DIR
+roles:
+  dir: ~/.prompts/roles       # Full path to roles directory
+
+# Skills Configuration
+# Access: AIA.config.skills.dir
+# Env: AIA_SKILLS__DIR
+#
+# Skills are subdirectories under skills.dir, each containing a SKILL.md
+# file with YAML front matter (name, description, and any custom fields).
+# Use --skill/-s to prepend skills to prompts, --list-skills to browse.
+skills:
+  dir: ~/.prompts/skills      # Directory containing skill subdirectories
+
 # Output Configuration
 # Access: AIA.config.output.file, AIA.config.output.append, etc.
 # Env: AIA_OUTPUT__FILE, AIA_OUTPUT__APPEND, etc.
@@ -191,9 +209,13 @@ export AIA_PROMPTS__EXTNAME=".md"
 export AIA_PROMPTS__ROLES_PREFIX="roles"
 export AIA_PROMPTS__ROLES_DIR="~/.prompts/roles"
 export AIA_PROMPTS__ROLE="expert"
+export AIA_PROMPTS__SKILLS_PREFIX="skills"
 export AIA_PROMPTS__SYSTEM_PROMPT="my_system_prompt"
 export AIA_PROMPTS__PARAMETER_REGEX='\{\{(\w+)\}\}'
 
+# Skills settings (nested under skills:)
+export AIA_SKILLS__DIR="~/.prompts/skills"
+
 # Output settings (nested under output:)
 export AIA_OUTPUT__FILE="/tmp/aia_output.md"
 export AIA_OUTPUT__APPEND="false"

data/docs/directives-reference.md

@@ -156,7 +156,7 @@ export PUREMD_API_KEY="your_api_key"
 **Aliases**: `/website`, `/web`
 
 ### `/skill`
-Include a Claude Code skill into the conversation context.
+Include an AIA skill into the conversation context.
 
 **Syntax**: `/skill skill_name`
 
@@ -169,38 +169,58 @@ Include a Claude Code skill into the conversation context.
 ```
 
 **Features**:
-- Reads `SKILL.md` from `~/.claude/skills/<skill_name>/`
+- Reads `SKILL.md` from the skills directory (default: `~/.prompts/skills/<skill_name>/`)
 - Supports prefix matching: `/skill code` finds the first subdirectory starting with "code"
 - Exact matches take priority over prefix matches
-- Returns the skill content for inclusion in the prompt
+- Injects only the **body content** of `SKILL.md` — the YAML front matter is stripped and never sent to the LLM
+- Skills directory is configured via `skills.dir` or `--skills-dir`
+
+**Role vs Skill**: A role defines the LLM's *personality*; a skill provides *task instructions* for how to carry out the user's request within that role. Skills are injected after the role and before the user prompt.
 
 **Error Handling**:
-- Missing skill name: `Error: /skill requires a skill name`
-- No matching directory: `Error: No skill matching 'name' found in ~/.claude/skills`
-- Directory exists but no SKILL.md: `Error: Skill directory 'name' has no SKILL.md`
+- Missing skill name: `Error: /skill requires a skill name. Use /skills to list available skills.`
+- No matching directory: `Error: No skill matching 'name' found in <dir>. Use /skills to list available skills.`
+- Directory exists but no SKILL.md: `Error: Skill directory 'name' has no SKILL.md. Use /skills to list available skills.`
+
+**See also**: `/skills` to list available skills, `--list-skills` CLI flag
 
 ### `/skills`
-List all available Claude Code skills.
+List available AIA skills with optional search filtering.
 
-**Syntax**: `/skills`
+**Syntax**: `/skills [search terms]`
+
+**Examples**:
+```markdown
+/skills                   # List all skills
+/skills ruby              # Skills matching "ruby"
+/skills -python           # Skills not matching "python"
+/skills ruby -deprecated  # Skills matching "ruby" but not "deprecated"
+```
+
+**Search term prefixes**:
+- Bare word or `+word` — positive filter (skill must match)
+- `-word`, `~word`, or `!word` — negative filter (skill must not match)
+- Searches skill name and SKILL.md front matter fields (name, description, etc.)
 
 **Example Output**:
 ```
-Available Skills
-================
-  algorithmic-art
-  api-developer
-  code-assist
+Available Skills (~/.prompts/skills):
+======================================
+
   code-quality
+    Improve code quality through comprehensive analysis and refactoring.
+
   frontend-design
+    Create distinctive, production-grade frontend interfaces.
 
-Total: 5 skills
+Total: 2 skills
 ```
 
 **Features**:
-- Lists subdirectory basenames from `~/.claude/skills/`
+- Lists skill subdirectories from `AIA.config.skills.dir` (default: `~/.prompts/skills/`)
 - Sorted alphabetically
 - Displays to STDOUT only (does not inject content into the prompt)
+- Reads `SKILL.md` front matter for filtering and description display
 
 ## Execution Directives