ask-skills 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a4c7549f41deea19983fb7bc68b3f8b0b97779b9cb164343608209bb64f5c61
-  data.tar.gz: 64db989863e81200f0985a45fa4c998bdff646bd9dad3f50031334baff34df62
+  metadata.gz: 6a8fc1e81c128476d7e6a3e5ce291213880f0d55a7261d41c7a99903e0c08431
+  data.tar.gz: 772dd0930f80b16fa8fb4b651245011899d5cf6406a8ad4a3a7c8002b17f435e
 SHA512:
-  metadata.gz: 244ee5c7ac9a6b69885cc659da57409a09f314bbb2d7fc045bc15fda179f6735e6d4462ebab47500d3507271cfcdb9baa9559e5ccbad233685b70528d799db64
-  data.tar.gz: d96732c2d1e7c966f85f8aae43caafa9ac5f8cafbdcd962c0c4dc94fdfa9d5dcf832701f70f07473f0e0e49427cc8783112a86c162438780f37c0707b6f5c1a4
+  metadata.gz: bb36fe31efde8c3757ee9dcd0be2b33e66dc105f5acc484432b1fd0217a6892032fdf5ded0a90fc7038e796398bb926a417cf877bea6cc46b6064296a524c649
+  data.tar.gz: 1e254bdaac3a75287aea4167f0d7a32781619e4836496809634cbc16244d35d18183782280c0476ca0853b00726ae4b46e445abddbc36098cf56c412477a59a8

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [0.5.0] - 2026-08-02
+
+### Removed
+
+- **Legacy `.agents/skills/` discovery path** — project skills now live in
+  `agents/shared/skills/` (or `app/agents/shared/skills/` in Rails). Move any
+  skills placed in `.agents/skills/` to the shared directory; nothing else
+  changes.
+
 ## [0.4.2] - 2026-07-31
 
 ### Fixed

data/README.md

@@ -2,13 +2,11 @@
 
 [![Gem Version](https://badge.fury.io/rb/ask-skills.svg)](https://badge.fury.io/rb/ask-skills)
 
-Discover, validate, and load agent skills from project directories, user config,
-and installed gems. Ships built-in skills for codebase exploration and debugging
-methodology.
-
-A **skill** is a markdown file containing step-by-step methodology for a specific
-domain task. It's listed in the agent's system prompt (just name + description)
-and loaded on-demand when the agent decides it needs domain guidance.
+Discover, validate, and load agent skills for the ask-rb ecosystem. A skill
+is a markdown file with step-by-step methodology for a domain task. Skills are
+listed in the agent's system prompt (name + description) and loaded on demand
+when the agent decides it needs domain guidance. Ships built-in skills
+(`skill.design`, `skill.compose`).
 
 ## Installation
 
@@ -16,181 +14,89 @@ and loaded on-demand when the agent decides it needs domain guidance.
 gem "ask-skills"
 ```
 
-Then:
+## Quick Start
 
 ```ruby
 require "ask/skills"
-```
-
-## Quick Start
 
-```ruby
-# Discover all available skills
+# Discover skills from project, user config, gems, and built-ins
 registry = Ask::Skills.discover
-# => Finds skills from:
-#    - Built-in skills (skill.design, skill.compose)
-#    - Installed gems (ask-rails, ask-github, etc.)
-#    - .agents/skills/*/ in the project
-#    - ~/.config/ask/skills/*/ in home dir
-
-# List available skills
-registry.names
-# => ["skill.compose", "skill.design"]
+registry.names   # => ["skill.compose", "skill.design", ...]
 
 # Get a skill by name
 skill = registry["skill.design"]
 skill.name         # => "skill.design"
-skill.description  # => "How to design and write effective skills for the ask-rb ecosystem"
+skill.description  # => "How to design and write effective skills..."
 skill.instructions # => markdown body with step-by-step methodology
 
-# Format for system prompt
-registry.format_for_prompt
-# => "## Available Skills\n\n- **skill.design**: How to design..."
-
-# XML format for machine parsing
-formatter = Ask::Skills::Formatter.new(registry)
-formatter.to_xml
-# => "<available_skills><skill><name>skill.design</name>..."
-
-# Validate skills
-errors = Ask::Skills::Validator.new(registry.skills.values).validate_all
+# Include per-agent skills too
+registry = Ask::Skills.discover(agent_dir: "agents/health_check")
 ```
 
-## Priority Resolution
+## Where Skills Live
 
-When the same skill name exists in multiple places, priority determines which
-one is used. **First source wins:**
-
-| Priority | Source | Location |
-|----------|--------|----------|
-| 1 (highest) | Project-local | `.agents/skills/<name>/SKILL.md` |
-| 2 | User-global | `~/.config/ask/skills/<name>/SKILL.md` |
-| 3 | Installed gems | `Gem.find_files("ask/skills/*/SKILL.md")` |
-| 4 (lowest) | Built-in | Shipped with ask-skills gem |
-
-This means you can override any skill by placing a file with the same name in
-your project's `.agents/skills/` directory.
-
-## Skill Directory Convention
+Project skills live in `agents/shared/skills/` (or `app/agents/shared/skills/`
+in Rails), per-agent skills in `agents/<name>/skills/`, user skills in
+`~/.config/ask/skills/`, and gems ship skills under `ask/skills/*/SKILL.md`.
 
 ```
-.agents/skills/
-├── db_debug/
-│   └── SKILL.md          ← project-local skill
-├── deploy/
-│   └── SKILL.md
-└── custom_check/
-    └── SKILL.md
+agents/shared/skills/
+└── db_debug/
+    └── SKILL.md          # project-shared skill
+
+agents/health_check/skills/
+└── nginx_debug/
+    ┗── SKILL.md          # per-agent skill
 
 ~/.config/ask/skills/
-├── my_workflow/
-│   └── SKILL.md          ← user-global skill
-└── team_patterns/
-    └── SKILL.md
-
-# From installed gems:
-ask-rails-0.2.0/lib/ask/skills/
-├── rails.db_debug/SKILL.md
-└── rails.deploy_pipeline/SKILL.md
-
-ask-github-0.1.0/lib/ask/skills/
-├── github.pr_review/SKILL.md
-└── github.issue_triage/SKILL.md
+└── my_workflow/
+    └── SKILL.md          # user-global skill
 ```
 
+When the same skill name exists in multiple places, the first source wins:
+per-agent > shared project (Rails included) > user > gems > built-in. Place a
+skill with the same name in a higher-priority location to override it.
+
 ## Skill Format
 
 ```markdown
 ---
-name: rails.db_debug
-description: Step-by-step methodology for debugging database issues in Rails
+name: db_debug
+description: Step-by-step methodology for debugging database issues
+tags: database, debugging
+version: 1
+author: your-team
+always: true
 ---
 
-When investigating database performance issues, follow these steps:
-
-1. **Understand the Schema** — Use ReadModel to inspect...
-2. **Check Indexes** — Query pg_indexes for missing indexes...
-3. **Explain Slow Queries** — Use EXPLAIN ANALYZE on...
+When investigating database performance issues, follow these steps...
 ```
 
-## Built-in Skills
-
-| Skill | Description |
-|-------|-------------|
-| `skill.design` | How to design and write effective skills for the ask-rb ecosystem |
-| `skill.compose` | How skills interact, combine, and resolve in the ask-rb ecosystem |
-
-## API Reference
+`always: true` auto-injects the full instructions into the system prompt
+instead of listing the skill for on-demand loading.
 
-### `Ask::Skills.discover(sources: nil)`
+## Essential API
 
-Returns a `Registry` with skills from all sources, in priority order.
-Pass `sources:` to override with custom sources.
-
-### `Ask::Skills::Registry`
-
-| Method | Description |
-|--------|-------------|
-| `[]` | Lookup skill by name |
-| `names` | List all skill names |
-| `skills` | Hash of name → Skill |
-| `format_for_prompt` | Generate markdown section |
-
-### `Ask::Skills::Skill` (Data.define)
-
-| Attribute | Description |
-|-----------|-------------|
-| `name` | Unique identifier (e.g. `rails.db_debug`) |
-| `description` | One-line summary for system prompt |
-| `instructions` | Full markdown methodology body |
-| `source` | File path the skill was loaded from |
-
-### `Ask::Skills::Formatter`
-
-| Method | Description |
-|--------|-------------|
-| `to_prompt_section` | Markdown format for system prompt |
-| `to_xml` | XML format for machine parsing |
-
-### `Ask::Skills::Validator`
-
-| Method | Description |
-|--------|-------------|
-| `validate_all` | Validate all skills, return errors |
-| `validate` | Validate a single skill |
-
-## Custom Sources
-
-```ruby
-require "ask/skills"
-
-# Custom filesystem source
-custom = Ask::Skills::Source::Filesystem.new(dir: "/path/to/skills")
-registry = Ask::Skills.discover(sources: [custom])
-```
+| Entry point | Purpose |
+|---|---|
+| `Ask::Skills.discover(agent_dir: nil, sources: nil)` | Build a `Registry` from all sources in priority order |
+| `registry["name"]` | Look up a skill by name |
+| `registry.names` | List all skill names |
+| `registry.skills` | Hash of name to `Skill` |
+| `Ask::Skills::Skill` | Data object: `name`, `description`, `instructions`, `source`, `metadata`, `siblings` (references, scripts, assets) |
+| `askr skills <list\|show\|search>` | CLI (from ask-agent) for inspecting available skills |
 
-## Gems That Ship Skills
+## Full documentation
 
-| Gem | Planned Skills |
-|---|---|
-| `ask-skills` (built-in) | skill.design, skill.compose |
-| `ask-rails` | rails.db_debug, rails.route_trouble, rails.deploy_pipeline |
-| `ask-github` | github.use_github |
-| `ask-slack` | slack.use_slack |
-| `ask-notion` | notion.use_notion |
-| `ask-linear` | linear.use_linear |
-| `ask-honeybadger` | honeybadger.use_honeybadger |
-| `ask-sentry` | sentry.use_sentry |
-| `ask-solid_errors` | solid_errors.use_solid_errors |
-| `ask-tools-shell` | shell.patterns |
-| `ask-llm-providers` | providers.model_select |
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.
+https://ask-rb.github.io/ask-docs/core/skills covers ask-skills in depth,
+including custom sources, the validator, and formatting for system prompts.
+API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 
-```bash
 bundle install
 bundle exec rake test
-```
 
 ## License
 

data/lib/ask/skills/skill.compose/SKILL.md

@@ -11,11 +11,12 @@ multiple places, the first source wins:
 1. **Built-in** (shipped with ask-skills gem) — lowest priority
 2. **Installed gems** (ask-rails, ask-github, etc.)
 3. **User-global** (`~/.config/ask/skills/`)
-4. **Project-local** (`.agents/skills/` in the project) — highest priority
+4. **Shared project** (`agents/shared/skills/`, or `app/agents/shared/skills/` in Rails)
+5. **Per-agent** (`agents/<name>/skills/`) — highest priority
 
 This means you can override any skill by placing a file with the same name in
-your project's `.agents/skills/` directory. Or provide personal defaults in
-`~/.config/ask/skills/`.
+`agents/shared/skills/` (or a per-agent `agents/<name>/skills/`). Or provide
+personal defaults in `~/.config/ask/skills/`.
 
 ## How Skills Appear in the System Prompt
 

data/lib/ask/skills/version.rb

@@ -1,5 +1,5 @@
 module Ask
   module Skills
-    VERSION = "0.4.2"
+    VERSION = "0.5.0"
   end
 end

data/lib/ask/skills.rb

@@ -28,7 +28,6 @@ module Ask
       end
 
       # Default sources when no custom sources or agent directory given.
-      # Legacy `.agents/skills/` is kept for backward compatibility.
       def default_sources
         build_source_list
       end
@@ -103,7 +102,7 @@ module Ask
       private
 
       # Build the prioritized source list.
-      # Order: per-agent → shared project → legacy → user → gems → built-in
+      # Order: per-agent → shared project → user → gems → built-in
       def build_source_list(agent_dir: nil)
         sources = []
 
@@ -117,9 +116,6 @@ module Ask
         sources << Source::Filesystem.new(project_dir: "agents/shared/skills")
         sources << Source::Filesystem.new(project_dir: "app/agents/shared/skills")
 
-        # Legacy project skills (backward compat)
-        sources << Source::Filesystem.new(project_dir: ".agents/skills")
-
         # User-global skills
         sources << Source::Filesystem.new(user_dir: "~/.config/ask/skills")
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-skills
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Kaka Ruto