ask-skills
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
gem "ask-skills"Quick Start
require "ask/skills"
# Discover skills from project, user config, gems, and built-ins
registry = Ask::Skills.discover
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..."
skill.instructions # => markdown body with step-by-step methodology
# Include per-agent skills too
registry = Ask::Skills.discover(agent_dir: "agents/health_check")Where Skills Live
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/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
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
---
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...always: true auto-injects the full instructions into the system prompt
instead of listing the skill for on-demand loading.
Essential API
| 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 |
Full documentation
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
bundle install bundle exec rake test
License
MIT