aia 1.0.0.pre.beta → 1.1.0

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.
 
@@ -259,7 +343,7 @@ Load configuration from a specific file.
 
 ```bash
 aia --config-file /path/to/config.yml my_prompt
-aia -c ~/.aia/custom_config.yml my_prompt
+aia -c ~/.config/aia/custom_config.yml my_prompt
 ```
 
 ### `-o, --[no-]output [FILE]`
@@ -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`
@@ -821,14 +912,6 @@ aia --output analysis.md --markdown --append data_analysis dataset.csv
 aia --transcription-model whisper-1 --speech-model tts-1-hd --voice echo audio_prompt audio_file.wav
 ```
 
-## Exit Codes
-
-- `0` - Success
-- `1` - General error (invalid arguments, file not found, etc.)
-- `2` - Configuration error
-- `3` - Model/API error
-- `4` - Tool execution error
-
 ## Environment Variables
 
 Many CLI options have corresponding environment variables with the `AIA_` prefix.

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.
@@ -167,25 +185,6 @@ paths:
 context_files: []
 ```
 
-### Model-Specific Configuration
-
-You can create model-specific configuration files:
-
-```yaml
-# ~/.config/aia/models/gpt-4.yml
-llm:
-  temperature: 0.3
-  max_tokens: 4000
-  top_p: 0.95
-```
-
-```yaml
-# ~/.config/aia/models/claude-3.yml
-llm:
-  temperature: 0.5
-  max_tokens: 8000
-```
-
 ## Environment Variables
 
 All configuration options can be set via environment variables with the `AIA_` prefix.
@@ -210,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"
@@ -255,7 +258,7 @@ export AIA_FLAGS__CLEAR="false"
 export AIA_FLAGS__CONSENSUS="false"
 
 # Logger settings (nested under logger:)
-export AIA_LOGGER__AIA__FILE="~/.aia/aia.log"
+export AIA_LOGGER__AIA__FILE="~/.config/aia/aia.log"
 export AIA_LOGGER__AIA__LEVEL="debug"
 export AIA_LOGGER__AIA__FLUSH="true"
 export AIA_LOGGER__LLM__FILE="STDOUT"
@@ -312,7 +315,7 @@ Each logger can be configured independently in your `~/.config/aia/aia.yml`:
 ```yaml
 logger:
   aia:
-    file: STDOUT           # STDOUT, STDERR, or a file path (e.g., ~/.aia/aia.log)
+    file: STDOUT           # STDOUT, STDERR, or a file path (e.g., ~/.config/aia/aia.log)
     level: warn            # debug, info, warn, error, fatal
     flush: true            # true = immediate write, false = buffered
   llm:
@@ -354,7 +357,7 @@ Logger settings can also be configured via environment variables:
 
 ```bash
 # AIA logger settings
-export AIA_LOGGER__AIA__FILE="~/.aia/aia.log"
+export AIA_LOGGER__AIA__FILE="~/.config/aia/aia.log"
 export AIA_LOGGER__AIA__LEVEL="debug"
 export AIA_LOGGER__AIA__FLUSH="true"
 
@@ -602,27 +605,17 @@ aia --tools ./my_tools --debug test_prompt
 
 ### Updating from Older Versions
 
-AIA automatically migrates older configuration formats. To manually update:
+If upgrading from an earlier version of AIA, back up and recreate your configuration:
 
 ```bash
 # Backup current config
 cp ~/.config/aia/aia.yml ~/.config/aia/aia.yml.backup
 
-# Update configuration format
-aia --migrate-config
+# Dump current running configuration as a starting point
+aia --dump ~/.config/aia/aia.yml
 ```
 
-### Configuration Templates
-
-Generate configuration templates:
-
-```bash
-# Generate basic config
-aia --generate-config basic > ~/.config/aia/aia.yml
-
-# Generate advanced config with all options
-aia --generate-config full > ~/.config/aia/aia.advanced.yml
-```
+Review the dumped file and merge any custom settings from your backup.
 
 ## Best Practices
 

data/docs/contributing.md

@@ -29,7 +29,7 @@ We welcome contributions to AIA! This guide will help you get started with contr
 ## Getting Started
 
 ### Prerequisites
-- Ruby 3.0+ installed
+- Ruby 3.2+ installed
 - Git for version control
 - Familiarity with AI/LLM concepts
 - Understanding of command-line tools
@@ -329,4 +329,4 @@ Questions? Feel free to open an issue or start a discussion on GitHub.
 
 ---
 
-*Last updated: December 2024*
+*Last updated: February 2026*

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 [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"
+```
 
-**Syntax**: `/skills`
+**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
 
@@ -544,32 +564,34 @@ ERROR: PUREMD_API_KEY is required in order to include a webpage
 
 ### Custom Directives
 
-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`:
 
 ```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:** Load custom directives with the --tools option:
+**Usage:** Load custom directives with the `--tools` option:
 
 ```bash
 # Load custom directive
-aia --tools examples/directives/ask.rb --chat
+aia --tools examples/directives/timestamp_directive.rb --chat
 
-# Use the custom directive in prompts
-/ask gather the latest closing data for the DOW, NASDAQ, and S&P 500
+# Use in chat mode
+/timestamp
+/timestamp %Y-%m-%d
 ```
 
+See `examples/directives/` for more examples.
+
 ### Best Practices
 
 1. **Test directives individually** before combining them

data/docs/examples/index.md

@@ -77,10 +77,10 @@ aia --pipeline "extract_data,analyze_data,generate_report" dataset.csv
 ### Custom Tool Integration
 ```bash
 # Copy a useful tool
-cp docs/examples/tools/file_analyzer.rb ~/.aia/tools/
+cp docs/examples/tools/file_analyzer.rb ~/.config/aia/tools/
 
 # Use it in a prompt
-aia --tools ~/.aia/tools/file_analyzer.rb analyze_project
+aia --tools ~/.config/aia/tools/file_analyzer.rb analyze_project
 ```
 
 ## Example Structure

data/docs/examples/mcp/index.md

@@ -110,62 +110,56 @@ server.connect();
 
 ### Basic MCP Configuration
 ```yaml
-# ~/.aia/config.yml
-mcp:
-  enabled: true
-  clients:
-    - name: github
-      command: ["python", "github_analyzer.py"]
-      env:
-        GITHUB_TOKEN: "${GITHUB_TOKEN}"
-        
-    - name: filesystem
-      command: ["node", "filesystem_analyzer.js"]
-      args: ["/allowed/path"]
-      
-    - name: database
-      command: ["python", "postgres_analyzer.py"]
-      env:
-        DATABASE_URL: "${DATABASE_URL}"
+# ~/.config/aia/aia.yml
+mcp_servers:
+  - name: github
+    command: python
+    args:
+      - github_analyzer.py
+    env:
+      GITHUB_TOKEN: "${GITHUB_TOKEN}"
+
+  - name: filesystem
+    command: node
+    args:
+      - filesystem_analyzer.js
+      - /allowed/path
+
+  - name: database
+    command: python
+    args:
+      - postgres_analyzer.py
+    env:
+      DATABASE_URL: "${DATABASE_URL}"
 ```
 
-### Advanced MCP Configuration
+### MCP Configuration with Timeouts
 ```yaml
-mcp:
-  enabled: true
-  security:
-    sandbox_mode: true
-    timeout: 30000  # 30 seconds
-    max_memory: "512MB"
-    
-  clients:
-    - name: github
-      command: ["python", "mcp_clients/github_analyzer.py"]
-      working_directory: "/opt/aia-mcp"
-      env:
-        GITHUB_TOKEN: "${GITHUB_TOKEN}"
-        LOG_LEVEL: "INFO"
-      security:
-        network_access: true
-        file_access: false
-        
-    - name: filesystem
-      command: ["node", "mcp_clients/filesystem_analyzer.js"]
-      args: ["/home/user/projects", "/tmp/workspace"]
-      security:
-        network_access: false
-        file_access: true
-        allowed_paths: ["/home/user/projects", "/tmp"]
-        
-    - name: database
-      command: ["python", "mcp_clients/postgres_analyzer.py"]
-      env:
-        DATABASE_URL: "${READ_ONLY_DB_URL}"
-        MAX_QUERY_TIME: "10000"
-      security:
-        network_access: true
-        file_access: false
-        read_only: true
+# ~/.config/aia/aia.yml
+mcp_servers:
+  - name: github
+    command: python
+    args:
+      - mcp_clients/github_analyzer.py
+    env:
+      GITHUB_TOKEN: "${GITHUB_TOKEN}"
+      LOG_LEVEL: "INFO"
+    timeout: 30000
+
+  - name: filesystem
+    command: node
+    args:
+      - mcp_clients/filesystem_analyzer.js
+      - /home/user/projects
+      - /tmp/workspace
+
+  - name: database
+    command: python
+    args:
+      - mcp_clients/postgres_analyzer.py
+    env:
+      DATABASE_URL: "${READ_ONLY_DB_URL}"
+    timeout: 10000
 ```
 
 ## Usage Examples
@@ -181,7 +175,7 @@ aia --mcp github repo_analysis --owner microsoft --repo vscode
 
 ```markdown
 # github_analysis.md
-/mcp github
+# Requires MCP server "github" configured in ~/.config/aia/aia.yml
 
 # GitHub Repository Analysis
 
@@ -208,7 +202,7 @@ aia --mcp database schema_analysis --schema public
 
 ```markdown
 # database_analysis.md
-/mcp database
+# Requires MCP server "database" configured in ~/.config/aia/aia.yml
 
 # Database Schema Analysis
 
@@ -227,7 +221,8 @@ Provide actionable optimization recommendations.
 ### Multi-Client Integration
 ```markdown
 # comprehensive_project_audit.md
-/mcp github,filesystem,database
+# Requires MCP servers: github, filesystem, database
+# Run with: aia --mcp-use github,filesystem,database comprehensive_project_audit
 
 # Comprehensive Project Audit
 
@@ -264,38 +259,36 @@ Generate unified recommendations with implementation priority.
 ## Security Considerations
 
 ### MCP Security Best Practices
+
+Control MCP server access using CLI flags:
+
+```bash
+# Allow only specific MCP servers
+aia --mcp-use github,filesystem --chat
+
+# Skip specific MCP servers
+aia --mcp-skip database --chat
+
+# Disable all MCP servers
+aia --no-mcp --chat
+```
+
+Limit what each MCP server can access through its configuration:
+
 ```yaml
-# Secure MCP configuration
-mcp:
-  security:
-    # Global security settings
-    default_timeout: 30000
-    max_memory_per_client: "256MB"
-    sandbox_mode: true
-    
-    # Network restrictions
-    allowed_domains: ["api.github.com", "localhost"]
-    blocked_domains: ["*.suspicious-domain.com"]
-    
-    # File system restrictions
-    allowed_paths: ["/home/user/projects", "/tmp/aia-workspace"]
-    blocked_paths: ["/etc", "/var", "/usr"]
-    
-  clients:
-    - name: github
-      security_profile: "network_only"
-      allowed_operations: ["read", "list"]
-      blocked_operations: ["write", "delete"]
-      
-    - name: filesystem
-      security_profile: "filesystem_readonly"
-      max_file_size: "10MB"
-      max_files_per_request: 100
-      
-    - name: database
-      security_profile: "database_readonly"
-      query_timeout: 10000
-      max_rows_per_query: 1000
+# ~/.config/aia/aia.yml
+mcp_servers:
+  - name: filesystem
+    command: mcp-server-filesystem
+    args:
+      - /home/user/projects     # Restrict to safe directories
+      - /tmp/aia-workspace
+
+  - name: database
+    command: database-mcp-server
+    env:
+      DATABASE_URL: "${READ_ONLY_DB_URL}"  # Use read-only credentials
+    timeout: 10000
 ```
 
 ### Access Control
@@ -388,18 +381,21 @@ python github_analyzer.py --test
 ```
 
 #### Protocol Errors
+
+Enable detailed MCP logging via the logger configuration:
+
 ```yaml
-# Enable detailed MCP logging
-mcp:
-  logging:
+# ~/.config/aia/aia.yml
+logger:
+  mcp:
+    file: /tmp/aia-mcp.log
     level: debug
-    file: /var/log/aia-mcp.log
-    include_request_response: true
-    
-  error_handling:
-    retry_attempts: 3
-    retry_delay: 1000
-    fallback_mode: graceful
+    flush: true
+```
+
+Or via CLI:
+```bash
+aia --debug my_prompt  # Sets all loggers to debug level
 ```
 
 #### Performance Issues

data/docs/examples/prompts/automation/index.md

@@ -89,8 +89,9 @@ aia --tools log_analyzer.rb incident_analysis /var/log/app.log
 ```
 
 ### MCP Integration
-```markdown
-/mcp filesystem,monitoring
+```bash
+# Run with MCP servers for filesystem access
+aia --mcp-use filesystem my_prompt
 ```
 
 ## Customization Parameters